docs: add actionable architecture guide and enforce planning skills

.agents/skills/adhoc-plan/SKILL.md

@@ -12,6 +12,9 @@ Execute this workflow when the user asks to turn recommended items into a concre
 
 - Repository root: `/Users/davidahmann/Projects/wrkr`
 - Recommendation source: user-provided recommended items for this run
+- Standards sources of truth:
+  - `/Users/davidahmann/Projects/wrkr/product/dev_guides.md`
+  - `/Users/davidahmann/Projects/wrkr/product/architecture_guides.md`
 - No dependency on `/Users/davidahmann/Projects/wrkr/product/ideas.md`
 - Planning-only skill. Do not implement code in this workflow.
 
@@ -25,28 +28,45 @@ Validation rules:
 - `output_plan_path` must resolve inside the repository and be writable.
 - If either input is missing or invalid, stop and output a blocker report.
 
+## Preconditions
+
+- `/Users/davidahmann/Projects/wrkr/product/dev_guides.md` must exist and be readable.
+- `/Users/davidahmann/Projects/wrkr/product/architecture_guides.md` must exist and be readable.
+- Both guides must contain enforceable rules for:
+  - testing and CI gating
+  - determinism and contract stability
+  - architecture/TDD/chaos/frugal governance requirements
+- If guides are missing or incomplete, stop and output a blocker report.
+
 ## Workflow
 
-1. Parse `recommended_items` and normalize each item to:
+1. Read `product/dev_guides.md` and `product/architecture_guides.md`; extract locked implementation and architecture constraints.
+2. Parse `recommended_items` and normalize each item to:
 - recommendation
 - why
 - strategic direction
 - expected moat/benefit
-2. Remove duplicates and out-of-scope items.
-3. Cluster recommendations into coherent epics.
-4. Prioritize with `P0/P1/P2` using contract risk, moat gain, adoption leverage, and dependency order.
-5. Create execution-ready stories with:
+3. Remove duplicates and out-of-scope items.
+4. Cluster recommendations into coherent epics.
+5. Prioritize with `P0/P1/P2` using contract risk, moat gain, adoption leverage, and dependency order.
+6. Create execution-ready stories with:
 - tasks
 - repo paths
 - run commands
 - test requirements
 - matrix wiring
 - acceptance criteria
-6. Add plan-level `Test Matrix Wiring`.
-7. Add `Recommendation Traceability` mapping recommendations to epic/story IDs.
-8. Add `Minimum-Now Sequence`, `Exit Criteria`, and `Definition of Done`.
-9. Verify quality gates.
-10. Overwrite `output_plan_path` with the final plan.
+7. For every story, enforce architecture fields:
+- architecture constraints
+- ADR required (`yes/no`)
+- TDD first failing test(s)
+- cost/perf impact (`low|medium|high`)
+- chaos/failure hypothesis (required for risk-bearing stories)
+8. Add plan-level `Test Matrix Wiring`.
+9. Add `Recommendation Traceability` mapping recommendations to epic/story IDs.
+10. Add `Minimum-Now Sequence`, `Exit Criteria`, and `Definition of Done`.
+11. Verify quality gates.
+12. Overwrite `output_plan_path` with the final plan.
 
 ## Command Contract (JSON Required)
 
@@ -66,10 +86,28 @@ Use `wrkr` commands with `--json` whenever the plan needs machine-readable evide
 - Respect architecture boundaries:
 - Go core authoritative for enforcement/verification
 - Python remains thin adoption layer
+- Enforce both standards guides in every generated plan:
+  - `product/dev_guides.md`
+  - `product/architecture_guides.md`
 - No dashboard-first scope in core backlog.
 - No minor polish as primary backlog.
 - Every story must include tests and matrix wiring.
 
+## Architecture Guides Enforcement Contract
+
+For stories touching architecture/risk/adapter/failure semantics, plan wiring must include:
+
+- `make prepush-full`
+
+For reliability/fault-tolerance stories, plan wiring must include:
+
+- `make test-hardening`
+- `make test-chaos`
+
+For performance-sensitive stories, plan wiring must include:
+
+- `make test-perf`
+
 ## Test Requirements by Work Type (Mandatory)
 
 1. Schema/artifact changes:
@@ -151,6 +189,11 @@ Story template:
 - `Test requirements:`
 - `Matrix wiring:`
 - `Acceptance criteria:`
+- `Architecture constraints:`
+- `ADR required: yes|no`
+- `TDD first failing test(s):`
+- `Cost/perf impact: low|medium|high`
+- `Chaos/failure hypothesis:` (required for risk-bearing stories)
 - Optional: `Dependencies:`, `Risks:`
 
 ## Quality Gate
@@ -163,6 +206,9 @@ Before finalizing:
 - Paths are real and repo-relevant.
 - Test requirements match story type.
 - Matrix wiring exists for every story.
+- Every story maps to enforceable rules from both guides (`dev_guides.md`, `architecture_guides.md`).
+- High-risk stories include hardening/chaos lane wiring.
+- CLI contract stories include explicit `--json` and exit-code invariants.
 - Sequence is dependency-aware and implementation-ready.
 
 ## Failure Mode

.agents/skills/backlog-plan/SKILL.md

@@ -12,6 +12,9 @@ Execute this workflow when asked to convert strategic feature recommendations in
 
 - Repository root: `/Users/davidahmann/Projects/wrkr`
 - Input file: `/Users/davidahmann/Projects/wrkr/product/ideas.md`
+- Standards sources of truth:
+  - `/Users/davidahmann/Projects/wrkr/product/dev_guides.md`
+  - `/Users/davidahmann/Projects/wrkr/product/architecture_guides.md`
 - Structure references (match level of detail and style):
 - `/Users/davidahmann/Projects/gait/product/PLAN_v1.md`
 - Output file: `/Users/davidahmann/Projects/wrkr/product/PLAN_NEXT.md` (unless user specifies a different target)
@@ -29,31 +32,57 @@ Execute this workflow when asked to convert strategic feature recommendations in
 
 If these are missing, stop and output a gap note instead of inventing details.
 
+- `product/dev_guides.md` and `product/architecture_guides.md` must exist and be readable.
+- Both guides must provide enforceable planning constraints for:
+  - testing/CI gates
+  - determinism/contracts
+  - architecture/TDD/chaos/frugal standards
+- If either guide is missing or incomplete, stop with a blocker report.
+
 ## Workflow
 
 1. Read `ideas.md` and extract candidate initiatives.
-2. Read reference plans to mirror structure and detail level.
-3. Cluster ideas into coherent epics (avoid one-idea-per-epic fragmentation).
-4. Prioritize using `P0/P1/P2` based on contract risk reduction, moat expansion, adoption leverage, and sequencing dependency.
-5. Produce execution-ready epics and stories.
-6. For every story, include concrete tasks, repo paths, run commands, acceptance criteria, test requirements, and CI matrix wiring.
-7. Build a plan-level test matrix section mapping stories to CI lanes (fast, integration, acceptance, cross-platform).
-8. Ensure each story defines tests based on work type (schema, CLI, gate/policy, determinism, runtime, SDK, docs/examples).
-9. Add explicit boundaries and non-goals to prevent scope drift.
-10. Add delivery sequencing section (phase/week-based minimum-now path).
-11. Add definition of done and release/exit gate criteria.
-12. Write full plan to target file, overwriting prior contents.
+2. Read `product/dev_guides.md` and `product/architecture_guides.md` and lock constraints into planning decisions.
+3. Read reference plans to mirror structure and detail level.
+4. Cluster ideas into coherent epics (avoid one-idea-per-epic fragmentation).
+5. Prioritize using `P0/P1/P2` based on contract risk reduction, moat expansion, adoption leverage, and sequencing dependency.
+6. Produce execution-ready epics and stories.
+7. For every story, include concrete tasks, repo paths, run commands, acceptance criteria, test requirements, CI matrix wiring, and architecture governance fields.
+8. Build a plan-level test matrix section mapping stories to CI lanes (fast, integration, acceptance, cross-platform).
+9. Ensure each story defines tests based on work type (schema, CLI, gate/policy, determinism, runtime, SDK, docs/examples).
+10. Add explicit boundaries and non-goals to prevent scope drift.
+11. Add delivery sequencing section (phase/week-based minimum-now path).
+12. Add definition of done and release/exit gate criteria.
+13. Write full plan to target file, overwriting prior contents.
 
 ## Non-Negotiables
 
 - Preserve Wrkr core contracts: determinism, offline-first defaults, fail-closed policy posture, schema stability, and exit code stability.
 - Respect architecture boundaries: Go core is authoritative for enforcement/verification logic; Python remains thin adoption layer.
+- Enforce both planning standards guides in all generated stories:
+  - `product/dev_guides.md`
+  - `product/architecture_guides.md`
 - Avoid dashboard-first or hosted-only dependencies in backlog core.
 - Do not include implementation code, pseudo-code, or ticket boilerplate.
 - Do not recommend minor polish work as primary backlog items.
 - Every story must include test requirements and explicit matrix wiring.
 - No story is complete without same-change test updates, except explicitly justified docs-only stories.
 
+## Architecture Guides Enforcement Contract
+
+For architecture/risk/adapter/failure stories, require wiring for:
+
+- `make prepush-full`
+
+For reliability/fault-tolerance stories, require wiring for:
+
+- `make test-hardening`
+- `make test-chaos`
+
+For performance-sensitive stories, require wiring for:
+
+- `make test-perf`
+
 ## Test Requirements by Work Type (Mandatory)
 
 1. Schema or artifact contract work:
@@ -131,6 +160,11 @@ Story template (required fields):
 - `Test requirements:`
 - `Matrix wiring:`
 - `Acceptance criteria:`
+- `Architecture constraints:`
+- `ADR required: yes|no`
+- `TDD first failing test(s):`
+- `Cost/perf impact: low|medium|high`
+- `Chaos/failure hypothesis:` (required for risk-bearing stories)
 - Optional when needed:
 - `Dependencies:`
 - `Risks:`
@@ -146,6 +180,9 @@ Before finalizing, verify:
 - Paths are real and repo-relevant.
 - Test requirements match story work type.
 - Matrix wiring is present for every story.
+- Every story maps to enforceable rules from both guides (`dev_guides.md`, `architecture_guides.md`).
+- High-risk stories include hardening/chaos lane wiring.
+- CLI contract stories include explicit `--json` and exit-code invariants.
 - Sequence is dependency-aware.
 - Plan stays strategic and execution-relevant (not cosmetic).
 

.agents/skills/initial-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: initial-plan
-description: Transform the Wrkr PRD in product/wrkr.md into a world-class, zero-ambiguity execution plan that mirrors the detail level of gait/product/PLAN_v1.md, while enforcing product/dev_guides.md coding, testing, CI, determinism, and contract standards. Use when the user asks for an initial build plan from the PRD (not from ideas/recommendations).
+description: Transform the Wrkr PRD in product/wrkr.md into a world-class, zero-ambiguity execution plan that mirrors the detail level of gait/product/PLAN_v1.md, while enforcing product/dev_guides.md and product/architecture_guides.md standards for coding, testing, CI, determinism, architecture governance, and contracts. Use when the user asks for an initial build plan from the PRD (not from ideas/recommendations).
 ---
 
 # PRD to Initial Execution Plan (Wrkr)
@@ -11,7 +11,9 @@ Execute this workflow when asked to create the initial execution plan from the W
 
 - Repository root: `/Users/davidahmann/Projects/wrkr`
 - Primary source of truth: `/Users/davidahmann/Projects/wrkr/product/wrkr.md`
-- Standards source of truth: `/Users/davidahmann/Projects/wrkr/product/dev_guides.md`
+- Standards sources of truth:
+  - `/Users/davidahmann/Projects/wrkr/product/dev_guides.md`
+  - `/Users/davidahmann/Projects/wrkr/product/architecture_guides.md`
 - Style reference (structure and depth): `/Users/davidahmann/Projects/wrkr/product/PLAN_v1.md`
 - Default output: `/Users/davidahmann/Projects/wrkr/product/PLAN_v1.0.md` (unless user specifies a different target path)
 - Planning only. Do not implement code or docs outside the target plan file.
@@ -26,7 +28,7 @@ Execute this workflow when asked to create the initial execution plan from the W
 - architecture and tech choices
 - CLI surfaces and expected behavior
 
-`dev_guides.md` must define enforceable engineering standards. At minimum:
+`product/dev_guides.md` and `product/architecture_guides.md` must define enforceable engineering standards. At minimum:
 - toolchain versions
 - lint/format requirements
 - testing tiers and commands
@@ -52,34 +54,41 @@ If these are missing, stop and output a gap note instead of inventing policy.
 - coverage gates, determinism, schema and exit code stability
 - security scanning and release integrity expectations
 
-3. Read `gait/product/PLAN_v1.md` to mirror structure depth and story-level specificity.
+3. Read `product/architecture_guides.md` and extract locked architecture execution standards:
+- TDD requirements and first-failing-test expectations
+- architecture constraints and ADR requirements
+- cloud-native execution factors beyond 12-factor expectations
+- frugal architecture/cost impact requirements
+- chaos/hardening/perf lane triggers and failure-hypothesis expectations
 
-4. Inspect current repository baseline and convert observed reality into a `Current Baseline (Observed)` section:
+4. Read `gait/product/PLAN_v1.md` to mirror structure depth and story-level specificity.
+
+5. Inspect current repository baseline and convert observed reality into a `Current Baseline (Observed)` section:
 - existing directories and key files
 - current CI/workflow state
 - current command surfaces and gaps versus PRD
 
-5. Build epics by implementation dependency, not by document order:
+6. Build epics by implementation dependency, not by document order:
 - Epic 0 foundations/scaffold/contracts
 - core runtime epics (source, detection, aggregation, identity, risk, proof, compliance)
 - CLI, regressions, and remediation flows
 - docs/acceptance/release hardening epics
 
-6. Decompose every epic into execution-ready stories with explicit tasks and test wiring.
+7. Decompose every epic into execution-ready stories with explicit tasks and test wiring.
 
-7. Add a plan-level `Test Matrix Wiring` section that maps stories to:
+8. Add a plan-level `Test Matrix Wiring` section that maps stories to:
 - Fast lane
 - Core CI lane
 - Acceptance lane
 - Cross-platform lane
 - Risk lane
 - Gating rule
 
-8. Add a dependency-aware `Minimum-Now Sequence` with phased/week execution order.
+9. Add a dependency-aware `Minimum-Now Sequence` with phased/week execution order.
 
-9. Add `Explicit Non-Goals` and `Definition of Done`.
+10. Add `Explicit Non-Goals` and `Definition of Done`.
 
-10. Write the plan to the target file, replacing prior contents.
+11. Write the plan to the target file, replacing prior contents.
 
 ## Non-Negotiables
 
@@ -115,6 +124,11 @@ Story template (required fields):
 - `Test requirements:`
 - `Matrix wiring:`
 - `Acceptance criteria:`
+- `Architecture constraints:`
+- `ADR required: yes|no`
+- `TDD first failing test(s):`
+- `Cost/perf impact: low|medium|high`
+- `Chaos/failure hypothesis:` (required for risk-bearing stories)
 - `Semantic invariants:` (required for stories touching identity/lifecycle/manifest/regress)
 - Optional when needed:
 - `Dependencies:`
@@ -159,6 +173,30 @@ For every story, derive required checks from `product/dev_guides.md` by work typ
 - Add command-smoke checks for documented flows.
 - Update acceptance scripts if operator workflow changed.
 
+## Architecture Guides Enforcement Contract
+
+For every story, enforce `product/architecture_guides.md` requirements:
+
+1. TDD requirements:
+- Capture first failing test(s) before implementation tasks.
+- Require red-green-refactor intent in story acceptance criteria where behavior changes.
+
+2. Architecture governance:
+- Specify architecture constraints for layer boundaries touched.
+- Mark `ADR required: yes` when changing boundary/data flow/contract/failure class.
+
+3. Frugal architecture:
+- Include cost/perf impact classification (`low|medium|high`).
+- For perf-sensitive stories, include `make test-perf`.
+
+4. Chaos/reliability operations:
+- Risk-bearing stories must include failure hypothesis and lane wiring for:
+  - `make test-hardening`
+  - `make test-chaos`
+
+5. Contract-first behavior:
+- CLI/JSON/exit-code stories must state explicit invariants in acceptance criteria.
+
 ## Testing Tier Mapping (Mandatory)
 
 When assigning `Test requirements:` and `Matrix wiring:` for each story, map to applicable dev-guides tiers explicitly:
@@ -218,15 +256,18 @@ Before finalizing, verify:
 - every epic traces back to specific FR/NFR/AC statements in `wrkr.md`
 - every story has concrete repo paths and executable commands
 - acceptance criteria are deterministic and objectively testable
-- test requirements match `dev_guides.md` tier expectations
+- test requirements match `dev_guides.md` and `architecture_guides.md` requirements
 - identity/lifecycle/manifest/regress stories include explicit semantic invariants
+- every story includes architecture constraints, TDD first-failing-test requirement, and cost/perf impact
+- high-risk stories include hardening/chaos lane wiring
+- CLI contract stories include explicit `--json` and exit-code invariants
 - matrix wiring exists for every story
 - sequence is dependency-aware and executable end-to-end
 - plan respects Wrkr boundaries (See product only; no Axym/Gait feature scope creep)
 
 ## Failure Mode
 
-If `wrkr.md` or `dev_guides.md` lacks required planning inputs, write only:
+If `wrkr.md`, `dev_guides.md`, or `architecture_guides.md` lacks required planning inputs, write only:
 
 - `No initial plan generated.`
 - `Reason:` concise blocker summary.