arey-pi 0.3.0 → 0.4.0

package/templates/adr.md

@@ -4,6 +4,16 @@
 
 Proposed
 
+Accepted values:
+Proposed,
+Accepted,
+Superseded,
+Deprecated.
+
+## Date
+
+YYYY-MM-DD
+
 ## Context
 
 Describe the forces,
@@ -11,13 +21,27 @@ constraints,
 requirements,
 and tradeoffs that make this decision necessary.
 
-## Decision
+Include:
+
+- the problem being solved;
+- relevant canonical specs or ADRs;
+- operational constraints;
+- security,
+  privacy,
+  performance,
+  reliability,
+  or maintainability concerns;
+- what happens if no decision is made.
 
-State the decision clearly.
+## Decision Drivers
+
+- Driver 1
+- Driver 2
+- Driver 3
 
 ## Options Considered
 
-### Option 1
+### Option 1: Name
 
 Summary.
 
@@ -29,7 +53,7 @@ Cons:
 
 - ...
 
-### Option 2
+### Option 2: Name
 
 Summary.
 
@@ -41,20 +65,65 @@ Cons:
 
 - ...
 
+## Decision
+
+State the chosen option clearly.
+
+Explain why it best satisfies the decision drivers.
+
 ## Consequences
 
-Describe expected consequences,
-including risks,
-costs,
-follow-up work,
-and operational impact.
+Expected positive consequences:
+
+- ...
+
+Expected negative consequences or costs:
+
+- ...
+
+Operational impact:
+
+- ...
+
+Follow-up work:
+
+- ...
+
+## Validation
+
+Describe how the decision will be validated.
+
+Examples:
+
+- tests;
+- operational metrics;
+- migration checks;
+- architecture review;
+- project readiness assessment.
 
 ## Supersession and Relationships
 
-Record whether this ADR supersedes,
-is superseded by,
-or overlaps with other ADRs.
+Supersedes:
+
+- None
+
+Superseded by:
+
+- None
+
+Related ADRs:
+
+- None
+
+Overlapping decisions:
+
+- None
 
 ## Revisit Conditions
 
-List conditions that should trigger review of this decision.
+Revisit this decision if:
+
+- a listed constraint changes;
+- implementation cost differs materially from expectations;
+- operational evidence contradicts assumptions;
+- a simpler option becomes viable.

package/templates/database.dbml

@@ -1,14 +1,57 @@
 // Canonical database specification.
-// Keep this DBML synchronised with migrations, ORM models, SQL DDL, constraints, indexes, and relationships.
+// Keep this DBML synchronised with migrations,
+// ORM models,
+// SQL DDL,
+// constraints,
+// indexes,
+// relationships,
+// and persistence tests.
 
 Project project_name {
   database_type: 'PostgreSQL'
-  Note: 'Replace this starter DBML with the canonical project schema.'
+  Note: '''
+    Replace this starter DBML with the canonical project schema.
+    Document the database engine,
+    important extensions,
+    ownership boundaries,
+    and migration constraints here.
+  '''
+}
+
+Enum example_status {
+  active
+  archived
 }
 
 Table example_entities {
   id uuid [pk, note: 'Primary identifier']
-  name varchar [not null]
+  name varchar [not null, unique, note: 'Human-readable unique name']
+  status example_status [not null, default: 'active']
   created_at timestamptz [not null]
   updated_at timestamptz [not null]
+
+  indexes {
+    name [unique, name: 'idx_example_entities_name_unique']
+    status [name: 'idx_example_entities_status']
+  }
+
+  Note: '''
+    Replace this example table with canonical project tables.
+    Include constraints,
+    indexes,
+    relationship intent,
+    and relevant domain notes.
+  '''
+}
+
+Table example_events {
+  id uuid [pk]
+  entity_id uuid [not null, ref: > example_entities.id]
+  event_type varchar [not null]
+  occurred_at timestamptz [not null]
+  payload jsonb [not null, default: '{}']
+
+  indexes {
+    (entity_id, occurred_at) [name: 'idx_example_events_entity_time']
+  }
 }

package/templates/feature.feature

@@ -1,17 +1,38 @@
-Feature: Feature name
-  As a stakeholder
-  I want a capability
-  So that an outcome is achieved
+@arey-pi @replace-me
+Feature: Replace with capability name
+  This feature is a canonical behaviour spec.
+  It should describe externally observable behaviour,
+  not implementation details.
 
-  Background:
-    Given relevant starting context
+  As a named actor or stakeholder
+  I want a concrete capability
+  So that a valuable outcome is achieved
 
-  Scenario: Observable behaviour
-    Given preconditions
-    When an action occurs
-    Then the expected outcome is observable
+  Rule: Replace with the business rule being protected
 
-  Scenario: Important edge case
-    Given edge-case preconditions
-    When an action occurs
-    Then the system handles the case explicitly
+    Background:
+      Given relevant starting context
+      And any shared preconditions that every scenario needs
+
+    @happy-path
+    Scenario: Primary successful behaviour
+      Given a meaningful initial state
+      When the actor performs the behaviour
+      Then the expected outcome is observable
+      And important side effects are visible
+
+    @validation @edge-case
+    Scenario Outline: Important validation or boundary behaviour
+      Given <precondition>
+      When the actor performs the behaviour with <input>
+      Then <outcome> is reported
+
+      Examples:
+        | precondition | input | outcome |
+        | valid setup   | value | result  |
+
+    @regression
+    Scenario: Regression behaviour
+      Given the historical failure condition
+      When the triggering action occurs
+      Then the regression is prevented