agile-context-engineering 0.2.2 → 0.3.0

package/agile-context-engineering/templates/wiki/coding-standards.xml

@@ -60,6 +60,44 @@
             - **NEVER leave stub implementations** — No `throw NotImplemented`, no `pass`, no `...`
             - If code exists in the codebase, it must be complete and functional
 
+            ### Defensive Programming — Zero Tolerance for Permissive Code
+
+            **WE USE DEFENSIVE PROGRAMMING + FAIL-FAST. PERMISSIVE PROGRAMMING IS BANNED.**
+
+            Permissive programming ("be liberal in what you accept") has caused catastrophic bugs.
+            It hides errors, delays failures, and makes debugging impossible. Every parameter must
+            be validated. Every error must be surfaced. No exceptions.
+
+            **MANDATORY — Do This:**
+            - **Validate EVERY input at the boundary** — check types, ranges, formats, required
+              fields BEFORE processing
+            - **Fail fast and loud** — if something is wrong, return an error immediately with a
+              clear message explaining WHAT is wrong and WHY
+            - **Read the function you're calling** — check its constructor/signature to know EXACTLY
+              what parameters it requires before writing the caller
+            - **Required means required** — if a function needs a value, the caller MUST provide it.
+              No nullable wrappers. No default fallbacks that mask missing data
+            - **Return errors, not defaults** — if a value is missing or invalid, return an error
+              string/throw, do NOT return `""`, `0`, `null`, `[]`, or any placeholder
+            - **Validate on BOTH client and server** — server validates before processing/pushing,
+              client validates as a redundant safety net. Both layers reject garbage
+            - **Surface errors visibly** — errors must reach whoever can fix them (the LLM, the user,
+              the developer). Log them, display them, return them. Never swallow them
+
+            **ABSOLUTELY FORBIDDEN — Never Do This:**
+            - `string? param = null` when the value is actually required — use `string param` and validate
+            - `return ""` or `return null` or `return []` when an operation fails — return an error with context
+            - `.optional()` or `.nullable()` on schema fields that the consuming function REQUIRES
+            - Fallback defaults that hide missing data (e.g., `value ?? defaultValue` to mask a null
+              that should never be null)
+            - `try/catch` that swallows exceptions and returns empty objects
+            - Silently stripping, transforming, or cleaning invalid data to make it pass validation
+            - Writing a caller without reading the callee's actual parameter signature first
+            - Using Postel's Law ("be liberal in what you accept") as justification for accepting garbage
+
+            **The Principle:**
+            **Garbage in → ERROR out. Never garbage in → silence.**
+
             ### No Assumptions
             - **Use LSPs first when available** — Check diagnostics, go-to-definition, and find-references before guessing. The LSP knows the codebase better than a text search.
             - **NEVER assume** libraries, classes, models, methods, or APIs exist

package/agile-context-engineering/templates/wiki/decizions.xml

@@ -1,115 +1,115 @@
-<decisions>
-    <purpose>
-        Template for `.docs/wiki/subsystems/[subsystem-name]/decisions/<decision-name>.md` — an
-        Architecture Decision Record (ADR) capturing WHY a significant choice was made.
-        Answers "Why did we choose X over Y?"
-
-        Each decision doc captures one significant technical decision with its context and
-        trade-offs. It is the document an AI agent reads to understand WHY things are built
-        a certain way, preventing it from making the wrong choice.
-
-        Create an ADR ONLY when a significant "why" decision was made:
-        - Choosing one approach over another with meaningful trade-offs
-        - Deviating from an established pattern for a specific reason
-        - Adopting a new technology, pattern, or architectural approach
-        - Rejecting a seemingly obvious solution for non-obvious reasons
-
-        Do NOT create ADRs for trivial or obvious decisions.
-
-        Complements:
-        - systems/ docs (WHAT exists — systems reference decisions that shaped them)
-        - patterns/ docs (HOW things work — patterns reference decisions that defined them)
-        - cross-cutting/ docs (shared infrastructure shaped by architectural decisions)
-    </purpose>
-
-    <template>
-        <decision-record>
-            # ADR-NNN: [Decision Title]
-
-            **Status**: Accepted | Superseded by [ADR-MMM](./ADR-MMM-slug.md)
-            **Date**: YYYY-MM-DD
-            **Story**: [story reference, if applicable]
-
-            ## Context
-            What situation prompted this decision. 2-3 sentences max.
-
-            ## Decision
-            What was decided. 2-3 sentences max.
-
-            ## Alternatives Considered
-            - **[Alternative A]**: [Why rejected — 1 sentence]
-            - **[Alternative B]**: [Why rejected — 1 sentence]
-
-            ## Consequences
-            - Pro: [positive outcome]
-            - Pro: [positive outcome]
-            - Con: [trade-off accepted]
-        </decision-record>
-    </template>
-
-    <guidelines>
-
-        **Documentation Style:**
-        - EXTREMELY SUCCINCT — each ADR should be under 30 lines
-        - NO FLUFF — every sentence must convey a decision, reason, or consequence
-        - Bullet points for alternatives and consequences
-        - Code references as `file-path:ClassName` only when the decision is about specific code
-
-        **ADR Numbering:**
-        - Sequential within the subsystem: ADR-001, ADR-002, etc.
-        - Filename format: `ADR-NNN-kebab-case-slug.md`
-        - To find the next number, read existing ADRs in the decisions/ directory.
-
-        **Status:**
-        - `Accepted` — the decision is in effect
-        - `Superseded by ADR-MMM` — replaced by a later decision (link to it)
-        - ADRs are IMMUTABLE — never edit an accepted ADR. Create a new one that supersedes it.
-
-        **Context:**
-        - 2-3 sentences. What problem or situation forced a choice.
-        - Reference the system or pattern this decision affects.
-
-        **Decision:**
-        - 2-3 sentences. What was chosen and at what scope.
-        - Be specific — "We use X for Y" not "We decided to improve things."
-
-        **Alternatives Considered:**
-        - List each rejected alternative with ONE sentence explaining why.
-        - If there were no meaningful alternatives, omit this section.
-
-        **Consequences:**
-        - Bullet list of pros and cons.
-        - Be honest about trade-offs — future agents need to know the downsides.
-        - Include migration/compatibility consequences if applicable.
-
-        **What does NOT belong here:**
-        - Implementation details (that's in systems/ and patterns/ docs)
-        - Step-by-step instructions (that's in guides/)
-        - Full analysis or research documents (those are in .ace/artifacts/)
-        - Revision history or meeting notes
-
-    </guidelines>
-
-    <evolution>
-
-        ADRs are IMMUTABLE once accepted. They are historical records.
-
-        **When to create a new ADR:**
-        - A significant architectural or pattern choice is made during a story
-        - An existing decision is reversed or significantly modified (supersede the old one)
-        - A new technology, pattern, or approach is adopted
-
-        **When NOT to create an ADR:**
-        - Routine implementation following existing patterns
-        - Bug fixes or refactoring that don't change architectural direction
-        - Trivial decisions with no meaningful trade-offs
-        - Decisions already captured in an existing ADR
-
-        **Superseding:**
-        - Create the new ADR with its own number
-        - Update the old ADR's Status to: `Superseded by [ADR-MMM](./ADR-MMM-slug.md)`
-        - This is the ONLY edit allowed on an accepted ADR
-
-    </evolution>
-
-</decisions>
+<decisions>
+    <purpose>
+        Template for `.docs/wiki/subsystems/[subsystem-name]/decisions/<decision-name>.md` — an
+        Architecture Decision Record (ADR) capturing WHY a significant choice was made.
+        Answers "Why did we choose X over Y?"
+
+        Each decision doc captures one significant technical decision with its context and
+        trade-offs. It is the document an AI agent reads to understand WHY things are built
+        a certain way, preventing it from making the wrong choice.
+
+        Create an ADR ONLY when a significant "why" decision was made:
+        - Choosing one approach over another with meaningful trade-offs
+        - Deviating from an established pattern for a specific reason
+        - Adopting a new technology, pattern, or architectural approach
+        - Rejecting a seemingly obvious solution for non-obvious reasons
+
+        Do NOT create ADRs for trivial or obvious decisions.
+
+        Complements:
+        - systems/ docs (WHAT exists — systems reference decisions that shaped them)
+        - patterns/ docs (HOW things work — patterns reference decisions that defined them)
+        - cross-cutting/ docs (shared infrastructure shaped by architectural decisions)
+    </purpose>
+
+    <template>
+        <decision-record>
+            # ADR-NNN: [Decision Title]
+
+            **Status**: Accepted | Superseded by [ADR-MMM](./ADR-MMM-slug.md)
+            **Date**: YYYY-MM-DD
+            **Story**: [story reference, if applicable]
+
+            ## Context
+            What situation prompted this decision. 2-3 sentences max.
+
+            ## Decision
+            What was decided. 2-3 sentences max.
+
+            ## Alternatives Considered
+            - **[Alternative A]**: [Why rejected — 1 sentence]
+            - **[Alternative B]**: [Why rejected — 1 sentence]
+
+            ## Consequences
+            - Pro: [positive outcome]
+            - Pro: [positive outcome]
+            - Con: [trade-off accepted]
+        </decision-record>
+    </template>
+
+    <guidelines>
+
+        **Documentation Style:**
+        - EXTREMELY SUCCINCT — each ADR should be under 30 lines
+        - NO FLUFF — every sentence must convey a decision, reason, or consequence
+        - Bullet points for alternatives and consequences
+        - Code references as `file-path:ClassName` only when the decision is about specific code
+
+        **ADR Numbering:**
+        - Sequential within the subsystem: ADR-001, ADR-002, etc.
+        - Filename format: `ADR-NNN-kebab-case-slug.md`
+        - To find the next number, read existing ADRs in the decisions/ directory.
+
+        **Status:**
+        - `Accepted` — the decision is in effect
+        - `Superseded by ADR-MMM` — replaced by a later decision (link to it)
+        - ADRs are IMMUTABLE — never edit an accepted ADR. Create a new one that supersedes it.
+
+        **Context:**
+        - 2-3 sentences. What problem or situation forced a choice.
+        - Reference the system or pattern this decision affects.
+
+        **Decision:**
+        - 2-3 sentences. What was chosen and at what scope.
+        - Be specific — "We use X for Y" not "We decided to improve things."
+
+        **Alternatives Considered:**
+        - List each rejected alternative with ONE sentence explaining why.
+        - If there were no meaningful alternatives, omit this section.
+
+        **Consequences:**
+        - Bullet list of pros and cons.
+        - Be honest about trade-offs — future agents need to know the downsides.
+        - Include migration/compatibility consequences if applicable.
+
+        **What does NOT belong here:**
+        - Implementation details (that's in systems/ and patterns/ docs)
+        - Step-by-step instructions (that's in guides/)
+        - Full analysis or research documents (those are in .ace/artifacts/)
+        - Revision history or meeting notes
+
+    </guidelines>
+
+    <evolution>
+
+        ADRs are IMMUTABLE once accepted. They are historical records.
+
+        **When to create a new ADR:**
+        - A significant architectural or pattern choice is made during a story
+        - An existing decision is reversed or significantly modified (supersede the old one)
+        - A new technology, pattern, or approach is adopted
+
+        **When NOT to create an ADR:**
+        - Routine implementation following existing patterns
+        - Bug fixes or refactoring that don't change architectural direction
+        - Trivial decisions with no meaningful trade-offs
+        - Decisions already captured in an existing ADR
+
+        **Superseding:**
+        - Create the new ADR with its own number
+        - Update the old ADR's Status to: `Superseded by [ADR-MMM](./ADR-MMM-slug.md)`
+        - This is the ONLY edit allowed on an accepted ADR
+
+    </evolution>
+
+</decisions>

package/agile-context-engineering/templates/wiki/guide.xml

@@ -1,137 +1,137 @@
-<guide>
-    <purpose>
-        Template for `.docs/wiki/subsystems/[subsystem-name]/guides/<task-name>.md` — a step-by-step
-        recipe for a common implementation task. Answers "How do I add/create/implement X?"
-
-        Each guide combines knowledge from multiple systems, patterns, and cross-cutting concerns
-        into one actionable recipe. It is the document an AI agent follows when performing a
-        recurring task end-to-end.
-
-        A "guide" is a task recipe for something developers do repeatedly:
-        e.g., "How to Add a New Drawing Tool", "How to Add a New CRUD Endpoint",
-        "How to Add a New Indicator", "How to Add a New Repository".
-
-        Complements:
-        - patterns/ docs (the structural patterns that guides reference)
-        - systems/ docs (the domain systems where guide steps take place)
-        - cross-cutting/ docs (the registrations and setup that guides include as steps)
-    </purpose>
-
-    <template>
-        <title>
-            # How to [Task]
-        </title>
-
-        <prerequisites>
-            ## Prerequisites
-
-            What you need to know or have in place before starting.
-            - Read: [Pattern Doc](../patterns/relevant-pattern.md) — understand the structural pattern
-            - Read: [System Doc](../systems/relevant-system.md) — understand the domain context
-            - Read: [Cross-Cutting Doc](../cross-cutting/relevant-concern.md) — understand registrations
-        </prerequisites>
-
-        <steps>
-            ## Steps
-
-            ### 1. [First Step]
-
-            What to do, where to do it, reference implementation to copy from.
-            - Create file: `[path]`
-            - Copy from: `file:ExistingImplementation` (closest reference)
-            - Key changes: [what to modify from the reference]
-
-            ### 2. [Second Step]
-
-            ...
-
-            ### 3. [Third Step]
-
-            ...
-        </steps>
-
-        <verification>
-            ## Verification
-
-            How to verify the implementation works.
-            - [ ] [Check 1]: [What to verify and how]
-            - [ ] [Check 2]: [What to verify and how]
-            - [ ] [Check 3]: [What to verify and how]
-        </verification>
-
-        <common-mistakes>
-            ## Common Mistakes
-
-            What people typically get wrong.
-            - [Mistake 1]: [Why it happens and how to avoid it]
-            - [Mistake 2]: [Why it happens and how to avoid it]
-        </common-mistakes>
-    </template>
-
-    <guidelines>
-
-        **Documentation Style:**
-        - EXTREMELY SUCCINCT — every word must add value
-        - NO FLUFF — direct, actionable information only
-        - Numbered steps — the agent follows these in order
-        - Code references as `file-path:ClassName.methodName` (not line numbers)
-        - Inline snippets ONLY for non-obvious configuration or registration code
-        - Every step must have a clear deliverable (a file created, a registration added, etc.)
-
-        **Prerequisites:**
-        - Link to the docs an agent should read BEFORE starting.
-        - Don't repeat content from those docs — just link.
-        - List any tools, dependencies, or environment requirements.
-
-        **Steps:**
-        - NUMBERED, ORDERED steps. An agent follows these sequentially.
-        - Each step has: WHAT to do, WHERE to do it, WHAT to copy from.
-        - Reference existing implementations as "copy from" targets — agents copy patterns, not invent.
-        - Include ALL steps: file creation, registration, configuration, wiring.
-        - Don't skip "obvious" steps — agents don't infer implicit requirements.
-
-        **Verification:**
-        - Checklist format. Agent runs through these after completing all steps.
-        - Include compilation check, runtime check, and behavioral check.
-        - Reference specific files or commands for verification.
-
-        **Common Mistakes:**
-        - Things agents (and developers) typically get wrong on first attempt.
-        - Each mistake should include WHY it happens and HOW to avoid it.
-        - Drawn from actual experience (gotchas from pattern and system docs).
-
-        **What does NOT belong here:**
-        - Detailed pattern explanations (link to patterns/ docs instead)
-        - System domain knowledge (link to systems/ docs instead)
-        - Cross-cutting mechanism details (link to cross-cutting/ docs instead)
-        - Story numbers, sprint context, revision history
-        - Testing strategy or test code (verification section covers basic checks only)
-
-    </guidelines>
-
-    <evolution>
-
-        This is a LIVING document — updated when the recipe changes.
-
-        **Update triggers:**
-        - New step required (new registration, new file to create)
-        - Step removed (registration no longer needed)
-        - Step order changed
-        - New common mistake discovered
-        - Reference implementation changed (new "copy from" target)
-        - Prerequisite docs added or removed
-
-        **NOT an update trigger:**
-        - New feature that follows the existing recipe without changes
-        - Bug fix in one implementation that followed the guide
-        - Internal refactoring that doesn't change the steps
-
-        **Update rules:**
-        - UPDATE steps when the recipe changes
-        - ADD new common mistakes as they are discovered
-        - UPDATE "copy from" references when better examples exist
-        - Keep the guide current — an agent should be able to follow it TODAY
-
-    </evolution>
-
-</guide>
+<guide>
+    <purpose>
+        Template for `.docs/wiki/subsystems/[subsystem-name]/guides/<task-name>.md` — a step-by-step
+        recipe for a common implementation task. Answers "How do I add/create/implement X?"
+
+        Each guide combines knowledge from multiple systems, patterns, and cross-cutting concerns
+        into one actionable recipe. It is the document an AI agent follows when performing a
+        recurring task end-to-end.
+
+        A "guide" is a task recipe for something developers do repeatedly:
+        e.g., "How to Add a New Drawing Tool", "How to Add a New CRUD Endpoint",
+        "How to Add a New Indicator", "How to Add a New Repository".
+
+        Complements:
+        - patterns/ docs (the structural patterns that guides reference)
+        - systems/ docs (the domain systems where guide steps take place)
+        - cross-cutting/ docs (the registrations and setup that guides include as steps)
+    </purpose>
+
+    <template>
+        <title>
+            # How to [Task]
+        </title>
+
+        <prerequisites>
+            ## Prerequisites
+
+            What you need to know or have in place before starting.
+            - Read: [Pattern Doc](../patterns/relevant-pattern.md) — understand the structural pattern
+            - Read: [System Doc](../systems/relevant-system.md) — understand the domain context
+            - Read: [Cross-Cutting Doc](../cross-cutting/relevant-concern.md) — understand registrations
+        </prerequisites>
+
+        <steps>
+            ## Steps
+
+            ### 1. [First Step]
+
+            What to do, where to do it, reference implementation to copy from.
+            - Create file: `[path]`
+            - Copy from: `file:ExistingImplementation` (closest reference)
+            - Key changes: [what to modify from the reference]
+
+            ### 2. [Second Step]
+
+            ...
+
+            ### 3. [Third Step]
+
+            ...
+        </steps>
+
+        <verification>
+            ## Verification
+
+            How to verify the implementation works.
+            - [ ] [Check 1]: [What to verify and how]
+            - [ ] [Check 2]: [What to verify and how]
+            - [ ] [Check 3]: [What to verify and how]
+        </verification>
+
+        <common-mistakes>
+            ## Common Mistakes
+
+            What people typically get wrong.
+            - [Mistake 1]: [Why it happens and how to avoid it]
+            - [Mistake 2]: [Why it happens and how to avoid it]
+        </common-mistakes>
+    </template>
+
+    <guidelines>
+
+        **Documentation Style:**
+        - EXTREMELY SUCCINCT — every word must add value
+        - NO FLUFF — direct, actionable information only
+        - Numbered steps — the agent follows these in order
+        - Code references as `file-path:ClassName.methodName` (not line numbers)
+        - Inline snippets ONLY for non-obvious configuration or registration code
+        - Every step must have a clear deliverable (a file created, a registration added, etc.)
+
+        **Prerequisites:**
+        - Link to the docs an agent should read BEFORE starting.
+        - Don't repeat content from those docs — just link.
+        - List any tools, dependencies, or environment requirements.
+
+        **Steps:**
+        - NUMBERED, ORDERED steps. An agent follows these sequentially.
+        - Each step has: WHAT to do, WHERE to do it, WHAT to copy from.
+        - Reference existing implementations as "copy from" targets — agents copy patterns, not invent.
+        - Include ALL steps: file creation, registration, configuration, wiring.
+        - Don't skip "obvious" steps — agents don't infer implicit requirements.
+
+        **Verification:**
+        - Checklist format. Agent runs through these after completing all steps.
+        - Include compilation check, runtime check, and behavioral check.
+        - Reference specific files or commands for verification.
+
+        **Common Mistakes:**
+        - Things agents (and developers) typically get wrong on first attempt.
+        - Each mistake should include WHY it happens and HOW to avoid it.
+        - Drawn from actual experience (gotchas from pattern and system docs).
+
+        **What does NOT belong here:**
+        - Detailed pattern explanations (link to patterns/ docs instead)
+        - System domain knowledge (link to systems/ docs instead)
+        - Cross-cutting mechanism details (link to cross-cutting/ docs instead)
+        - Story numbers, sprint context, revision history
+        - Testing strategy or test code (verification section covers basic checks only)
+
+    </guidelines>
+
+    <evolution>
+
+        This is a LIVING document — updated when the recipe changes.
+
+        **Update triggers:**
+        - New step required (new registration, new file to create)
+        - Step removed (registration no longer needed)
+        - Step order changed
+        - New common mistake discovered
+        - Reference implementation changed (new "copy from" target)
+        - Prerequisite docs added or removed
+
+        **NOT an update trigger:**
+        - New feature that follows the existing recipe without changes
+        - Bug fix in one implementation that followed the guide
+        - Internal refactoring that doesn't change the steps
+
+        **Update rules:**
+        - UPDATE steps when the recipe changes
+        - ADD new common mistakes as they are discovered
+        - UPDATE "copy from" references when better examples exist
+        - Keep the guide current — an agent should be able to follow it TODAY
+
+    </evolution>
+
+</guide>