diff --git a/specification/etc/specification.png b/specification/etc/specification.png
new file mode 100644
index 000000000..a69041363
Binary files /dev/null and b/specification/etc/specification.png differ
diff --git a/specification/etc/specification.ucls b/specification/etc/specification.ucls
new file mode 100644
index 000000000..63dc2ee32
--- /dev/null
+++ b/specification/etc/specification.ucls
@@ -0,0 +1,212 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/specification/src/main/java/com/iluwatar/app/App.java b/specification/src/main/java/com/iluwatar/app/App.java
index 85f9a386b..b078907b9 100644
--- a/specification/src/main/java/com/iluwatar/app/App.java
+++ b/specification/src/main/java/com/iluwatar/app/App.java
@@ -16,7 +16,21 @@ import com.iluwatar.property.Movement;
import com.iluwatar.selector.ColorSelector;
import com.iluwatar.selector.MovementSelector;
+/**
+ *
+ * The central idea of Specification pattern is to separate the statement of how to match a candidate, from the
+ * candidate object that it is matched against. As well as its usefulness in selection, it is also valuable for
+ * validation and for building to order.
+ *
+ * In this example we have a pool of creatures with different properties. We then have defined separate selection
+ * rules (Specifications) that we apply to the collection and as output receive only the creatures that match
+ * the selection criteria.
+ *
+ * http://martinfowler.com/apsupp/spec.pdf
+ *
+ */
public class App {
+
public static void main( String[] args ) {
// initialize creatures list
List creatures = Arrays.asList(new Goblin(), new Octopus(), new Dragon(), new Shark(), new Troll(), new KillerBee());
diff --git a/specification/src/main/java/com/iluwatar/creature/AbstractCreature.java b/specification/src/main/java/com/iluwatar/creature/AbstractCreature.java
index e07144836..c6294bd4a 100644
--- a/specification/src/main/java/com/iluwatar/creature/AbstractCreature.java
+++ b/specification/src/main/java/com/iluwatar/creature/AbstractCreature.java
@@ -4,6 +4,11 @@ import com.iluwatar.property.Color;
import com.iluwatar.property.Movement;
import com.iluwatar.property.Size;
+/**
+ *
+ * Base class for concrete creatures.
+ *
+ */
public abstract class AbstractCreature implements Creature {
private String name;
diff --git a/specification/src/main/java/com/iluwatar/creature/Creature.java b/specification/src/main/java/com/iluwatar/creature/Creature.java
index eb49b5a77..1844db804 100644
--- a/specification/src/main/java/com/iluwatar/creature/Creature.java
+++ b/specification/src/main/java/com/iluwatar/creature/Creature.java
@@ -4,6 +4,11 @@ import com.iluwatar.property.Color;
import com.iluwatar.property.Movement;
import com.iluwatar.property.Size;
+/**
+ *
+ * Creature interface.
+ *
+ */
public interface Creature {
String getName();
diff --git a/specification/src/main/java/com/iluwatar/creature/Dragon.java b/specification/src/main/java/com/iluwatar/creature/Dragon.java
index d7a93f74c..a925c60b9 100644
--- a/specification/src/main/java/com/iluwatar/creature/Dragon.java
+++ b/specification/src/main/java/com/iluwatar/creature/Dragon.java
@@ -4,6 +4,11 @@ import com.iluwatar.property.Color;
import com.iluwatar.property.Movement;
import com.iluwatar.property.Size;
+/**
+ *
+ * Dragon creature.
+ *
+ */
public class Dragon extends AbstractCreature {
public Dragon() {
diff --git a/specification/src/main/java/com/iluwatar/creature/Goblin.java b/specification/src/main/java/com/iluwatar/creature/Goblin.java
index 4f584756d..19bdac7f1 100644
--- a/specification/src/main/java/com/iluwatar/creature/Goblin.java
+++ b/specification/src/main/java/com/iluwatar/creature/Goblin.java
@@ -4,6 +4,11 @@ import com.iluwatar.property.Color;
import com.iluwatar.property.Movement;
import com.iluwatar.property.Size;
+/**
+ *
+ * Goblin creature.
+ *
+ */
public class Goblin extends AbstractCreature {
public Goblin() {
diff --git a/specification/src/main/java/com/iluwatar/creature/KillerBee.java b/specification/src/main/java/com/iluwatar/creature/KillerBee.java
index bbb906bf1..e2ebf4d1f 100644
--- a/specification/src/main/java/com/iluwatar/creature/KillerBee.java
+++ b/specification/src/main/java/com/iluwatar/creature/KillerBee.java
@@ -4,6 +4,11 @@ import com.iluwatar.property.Color;
import com.iluwatar.property.Movement;
import com.iluwatar.property.Size;
+/**
+ *
+ * KillerBee creature.
+ *
+ */
public class KillerBee extends AbstractCreature {
public KillerBee() {
diff --git a/specification/src/main/java/com/iluwatar/creature/Octopus.java b/specification/src/main/java/com/iluwatar/creature/Octopus.java
index b3bab86b9..f40030475 100644
--- a/specification/src/main/java/com/iluwatar/creature/Octopus.java
+++ b/specification/src/main/java/com/iluwatar/creature/Octopus.java
@@ -4,6 +4,11 @@ import com.iluwatar.property.Color;
import com.iluwatar.property.Movement;
import com.iluwatar.property.Size;
+/**
+ *
+ * Octopus creature.
+ *
+ */
public class Octopus extends AbstractCreature {
public Octopus() {
diff --git a/specification/src/main/java/com/iluwatar/creature/Shark.java b/specification/src/main/java/com/iluwatar/creature/Shark.java
index 3ae40a342..a751cc605 100644
--- a/specification/src/main/java/com/iluwatar/creature/Shark.java
+++ b/specification/src/main/java/com/iluwatar/creature/Shark.java
@@ -4,6 +4,11 @@ import com.iluwatar.property.Color;
import com.iluwatar.property.Movement;
import com.iluwatar.property.Size;
+/**
+ *
+ * Shark creature.
+ *
+ */
public class Shark extends AbstractCreature {
public Shark() {
diff --git a/specification/src/main/java/com/iluwatar/creature/Troll.java b/specification/src/main/java/com/iluwatar/creature/Troll.java
index 82178042b..3773c6e93 100644
--- a/specification/src/main/java/com/iluwatar/creature/Troll.java
+++ b/specification/src/main/java/com/iluwatar/creature/Troll.java
@@ -4,6 +4,11 @@ import com.iluwatar.property.Color;
import com.iluwatar.property.Movement;
import com.iluwatar.property.Size;
+/**
+ *
+ * Troll creature.
+ *
+ */
public class Troll extends AbstractCreature {
public Troll() {
diff --git a/specification/src/main/java/com/iluwatar/property/Color.java b/specification/src/main/java/com/iluwatar/property/Color.java
index 52238b13b..4ee16063a 100644
--- a/specification/src/main/java/com/iluwatar/property/Color.java
+++ b/specification/src/main/java/com/iluwatar/property/Color.java
@@ -1,5 +1,10 @@
package com.iluwatar.property;
+/**
+ *
+ * Color property.
+ *
+ */
public enum Color {
DARK("dark"), LIGHT("light"), GREEN("green"), RED("red");
diff --git a/specification/src/main/java/com/iluwatar/property/Movement.java b/specification/src/main/java/com/iluwatar/property/Movement.java
index a4b29deb8..9fcdc4d23 100644
--- a/specification/src/main/java/com/iluwatar/property/Movement.java
+++ b/specification/src/main/java/com/iluwatar/property/Movement.java
@@ -1,5 +1,10 @@
package com.iluwatar.property;
+/**
+ *
+ * Movement property.
+ *
+ */
public enum Movement {
WALKING("walking"), SWIMMING("swimming"), FLYING("flying");
diff --git a/specification/src/main/java/com/iluwatar/property/Size.java b/specification/src/main/java/com/iluwatar/property/Size.java
index d97775ea4..2fbbdb2dc 100644
--- a/specification/src/main/java/com/iluwatar/property/Size.java
+++ b/specification/src/main/java/com/iluwatar/property/Size.java
@@ -2,7 +2,7 @@ package com.iluwatar.property;
/**
*
- * Enumeration for creature size.
+ * Size property.
*
*/
public enum Size {
diff --git a/specification/src/main/java/com/iluwatar/selector/ColorSelector.java b/specification/src/main/java/com/iluwatar/selector/ColorSelector.java
index 07e437b4c..532c79e89 100644
--- a/specification/src/main/java/com/iluwatar/selector/ColorSelector.java
+++ b/specification/src/main/java/com/iluwatar/selector/ColorSelector.java
@@ -5,6 +5,11 @@ import java.util.function.Predicate;
import com.iluwatar.creature.Creature;
import com.iluwatar.property.Color;
+/**
+ *
+ * Color selector.
+ *
+ */
public class ColorSelector implements Predicate {
private final Color c;
diff --git a/specification/src/main/java/com/iluwatar/selector/MovementSelector.java b/specification/src/main/java/com/iluwatar/selector/MovementSelector.java
index 5fe7ce40a..076e0ea5d 100644
--- a/specification/src/main/java/com/iluwatar/selector/MovementSelector.java
+++ b/specification/src/main/java/com/iluwatar/selector/MovementSelector.java
@@ -5,6 +5,11 @@ import java.util.function.Predicate;
import com.iluwatar.creature.Creature;
import com.iluwatar.property.Movement;
+/**
+ *
+ * Movement selector.
+ *
+ */
public class MovementSelector implements Predicate {
private final Movement m;
diff --git a/specification/src/main/java/com/iluwatar/selector/SizeSelector.java b/specification/src/main/java/com/iluwatar/selector/SizeSelector.java
index 1242920f7..58d705839 100644
--- a/specification/src/main/java/com/iluwatar/selector/SizeSelector.java
+++ b/specification/src/main/java/com/iluwatar/selector/SizeSelector.java
@@ -5,6 +5,11 @@ import java.util.function.Predicate;
import com.iluwatar.creature.Creature;
import com.iluwatar.property.Size;
+/**
+ *
+ * Size selector.
+ *
+ */
public class SizeSelector implements Predicate {
private final Size s;