archspec 1.6.3 → 1.7.0

package/lib/init.js

@@ -1,12 +1,15 @@
 const createFolderWithFiles = require("./createFolderWithFiles");
 const architectureTemplates = require("./templates/architecture");
 const governanceTemplates = require("./templates/governance");
-
+const implementationTemplates = require("./templates/implementation");
+const executionTemplates = require("./templates/execution");
 
 function init() {
   createFolderWithFiles("architecture", architectureTemplates);
   createFolderWithFiles("governance", governanceTemplates);
-  console.log("Architecture and Governance folders initialized.");
+  createFolderWithFiles("implementation", implementationTemplates);
+  createFolderWithFiles("execution", executionTemplates);
+  console.log("Architecture, Governance, Implementation and Execution folders initialized.");
 }
 
 module.exports = init;

package/lib/templates/execution.js

@@ -0,0 +1,1010 @@
+const executionTemplates = {
+    "README.md": `# Execution
+
+This directory defines how **approved implementation decisions** are executed.
+
+Execution is a downstream system.
+
+It does NOT define architecture.
+It does NOT define implementation structure.
+It does NOT introduce new requirements.
+
+Execution translates approved state into:
+
+* Phased delivery
+* Layer sequencing
+* Test enforcement
+* Operational tracking
+
+---
+
+## Source of Truth
+
+Execution is derived from:
+
+* architecture/architecture.md
+* implementation/implementation.md
+* execution/execution.config.md
+
+The following files are GENERATED:
+
+* execution-plan.md
+* test-strategy.md
+
+They must never be edited manually.
+
+---
+
+## Governance Rules
+
+* Execution may only act on layers defined in architecture.
+* Execution may only act on approved implementation decisions.
+* No phase may introduce new structural rules.
+* No task may exist without a corresponding approved decision.
+* No domain logic may appear in execution artifacts.
+* If ambiguity exists, it must be recorded in open-questions.md.
+
+Execution is operational, not architectural.
+
+---
+
+## Phase Discipline
+
+* Phases are declarative and defined in execution.config.md.
+* Layers must match architecture layer names exactly.
+* Phases are executed sequentially.
+* No future-phase work may be implemented early.
+* Each phase must pass defined tests before completion.
+
+---
+
+## Testing Discipline
+
+All execution phases must enforce:
+
+* Passing unit tests
+* Passing integration tests (where applicable)
+* Passing E2E tests (if defined)
+* No TypeScript errors
+* No console errors
+
+Testing requirements are generated in test-strategy.md.
+
+---
+
+## System Philosophy
+
+Architecture defines structure.
+Implementation defines stack.
+Execution defines sequencing.
+
+Execution is the operational layer of governance.
+
+It compiles declared structure into deterministic delivery.
+
+---
+`,
+  "init.md": `# Deterministic Execution Planning
+
+## 1. Create the files (once)
+
+In your repo root:
+
+/execution
+  ├─ execution.config.md      ← ONLY editable execution truth
+  ├─ execution-plan.md        ← GENERATED, read-only
+  ├─ test-strategy.md         ← GENERATED, read-only
+  └─ README.md                ← rules
+
+---
+
+## 2. Initialize execution.config.md
+
+Paste this exactly, until the line \`-- END OF PASTING --\`:
+
+
+# Execution Configuration
+
+## Rules
+- execution.config.md is the ONLY source of truth for execution phases
+- execution-plan.md is GENERATED and must never be edited manually
+- test-strategy.md is GENERATED and must never be edited manually
+- Phases are declarative
+- Layers must match Architecture Layers exactly
+- No layer may exist in execution without existing in architecture
+
+## Phase Definition Format
+
+Each phase must:
+- Have a unique ID
+- Have a Name
+- Either define Layers OR Type: e2e
+- Have a Status (active | planned | deprecated)
+
+---
+
+## Phases
+
+[PH-001]
+Name: Phase 1 – Backend Core
+Layers:
+- Infra
+- DAL
+- Services
+- Controllers
+- Routes
+Status: active
+
+[PH-002]
+Name: Phase 2 – Frontend Core
+Layers:
+- Infra
+- API Service
+- FE Services
+- Context
+- Components
+Status: planned
+
+[PH-003]
+Name: Phase 3 – E2E
+Type: e2e
+Status: planned
+
+-- END OF PASTING --
+
+This file represents the execution state.
+
+---
+
+## 3. Make generated files read-only (discipline rule)
+
+For both:
+
+execution-plan.md
+test-strategy.md
+
+Enforce:
+
+* Never manually edit
+* Treat like \`/dist\`
+* Add this header at the top of each file:
+
+<!-- GENERATED FILE – DO NOT EDIT -->
+
+---
+
+## 4. Create Cursor Agents
+
+Create the following agents:
+
+### 1) Execution Plan Generator Agent
+
+Responsible for:
+
+* Reading architecture/architecture.decisions.md
+* Reading execution/execution.config.md
+* Validating that all referenced layers exist
+* Generating execution-plan.md
+
+### 2) Test Strategy Generator Agent
+
+Responsible for:
+
+* Reading architecture layers
+* Reading execution phases
+* Generating test-strategy.md dynamically based on layer categories
+
+### 3) Execution Validator Agent (optional but recommended)
+
+Responsible for:
+
+* Ensuring phase layers exist in architecture
+* Preventing orphan layers
+* Preventing drift between execution and architecture
+
+---
+
+## 5. Governance Rules
+
+* execution-plan.md and test-strategy.md must never contain handwritten content
+* Any manual edits must be overwritten on next generation
+* Execution phases must remain aligned with architecture layers
+* E2E phases must not introduce business-specific logic
+* No domain-specific flows (e.g. “submit answer”) are allowed in generated files
+
+---
+
+## Execution Philosophy
+
+Architecture defines structure.
+Implementation defines stack.
+Execution defines phase grouping.
+
+All three are declarative state files.
+Everything else is generated.
+
+---
+
+
+`,
+    "execution-plan.md": `## Placeholder
+
+Execution plan not yet generated.
+
+Run execution plan generator to populate this file.
+  `,
+  
+    "test-strategy.md": `## Placeholder
+
+Test strategy not yet generated.
+
+Run test strategy generator to populate this file.
+  `,
+  
+    "open-questions.md": `# Open Questions Log
+
+This file records ambiguities encountered during deterministic execution.
+
+Rules:
+
+* Questions must follow the exact structure below.
+* No prose outside the defined structure.
+* Questions must reference an existing layer.
+* Questions must be execution-blocking ambiguities only.
+* This file may only be appended to.
+* Resolved questions must have Status updated to: Resolved.
+* Execution agents must NOT guess answers.
+
+---
+
+## Structure Example
+
+## Q-001
+
+Context: API Service
+Question: Should base URL differ between dev and prod?
+Status: Open
+
+## Q-002
+
+Context: DAL
+Question: Should timestamps be ISO strings or Date objects?
+Status: Open
+
+---
+
+## Q-003
+
+Context: Execution
+Question: execution-plan.md defines Phase 1 as active. Should execution stop automatically after Phase 1 completion, or continue into next planned phase?
+Status: Open
+
+## Q-004
+
+Context: Services
+Question: execution-plan.md requires unit tests for Services layer. Should mocking of external dependencies (OpenAI, Neo4j, Chroma) be mandatory for deterministic tests?
+Status: Open
+
+## Q-005
+
+Context: Controllers
+Question: If execution-plan.md requires integration tests, should controller tests include real database connections or use in-memory substitutes?
+Status: Open
+
+## Q-006
+
+Context: Routes
+Question: test-strategy.md requires route-level tests. Should supertest run against a live server instance or an injected Express app?
+Status: Open
+
+## Q-007
+
+Context: Infra
+Question: execution requires SQLite DB connected. Should the database file be created automatically during test setup if missing?
+Status: Open
+
+## Q-008
+
+Context: Execution
+Question: If test-strategy.md defines E2E tests but no E2E phase is active, should E2E tests be skipped or fail execution?
+Status: Open
+
+## Q-009
+
+Context: Components
+Question: execution-plan.md requires no console errors. Should console warnings be treated as execution failures?
+Status: Open
+
+## Q-010
+
+Context: FE Services
+Question: If an API route returns unexpected shape but no explicit schema contract exists in implementation.md, should execution fail or log ambiguity?
+Status: Open
+
+---
+
+
+  `,
+  
+    "agents-prompts.md": `
+
+# Execution Agent Prompts
+
+This document defines the **exact prompts** used to operate the execution planning system in this repository.
+
+These prompts are part of execution governance.
+They must remain stable and should not be casually modified.
+
+---
+
+## 1. Execution Plan Generator Agent (Decision-Driven Deterministic Planner)
+
+<!-- ⚠️ This agent MUST be run in Agent mode, never in plan or explanation mode. -->
+
+You are the **Execution Plan Generator Agent**.
+
+You produce a **decision-driven execution plan**.
+Your output must be richer than \`execution.config.md\` and must be derived deterministically from **approved decisions**.
+
+### Input (read only)
+
+* \`architecture/architecture.decisions.md\`
+* \`implementation/implementation.decisions.md\`
+* \`execution/execution.config.md\`
+
+### Output (write only)
+
+* \`execution/execution-plan.md\`
+
+---
+
+### Rules
+
+#### Hard constraints
+
+* Read **ONLY** the three input files listed above.
+* Do **NOT** read source code files.
+* Do **NOT** read generated files (\`architecture.md\`, \`implementation.md\`, existing \`execution-plan.md\`).
+* Do **NOT** invent business flows, user journeys, or domain-specific behavior.
+* Do **NOT** guess missing requirements.
+* If required info is missing to generate a correct plan, output a blocking issues bullet list instead of generating the file.
+
+#### Determinism constraints
+
+* Generate \`execution/execution-plan.md\` **from scratch**.
+* Ignore any existing \`execution-plan.md\`.
+* Use **stable, minimal wording**.
+* Preserve **phase names** exactly as in \`execution.config.md\`.
+* Preserve **layer names** exactly as in \`execution.config.md\`.
+* Preserve **decision IDs** exactly as in \`implementation.decisions.md\`.
+* Only use decisions with \`Status: approved\`.
+
+### Scope constraints
+
+* Execution content may only be derived from:
+
+  * Phase structure in \`execution.config.md\`
+  * Architecture layer existence in \`architecture.decisions.md\`
+  * Tooling/stack selections in \`implementation.decisions.md\`
+* Never introduce tasks unrelated to an approved implementation decision.
+
+---
+
+### Validation (must run before generation)
+
+You must validate ALL of the following:
+
+1. Every layer referenced in \`execution.config.md\` exists in \`architecture/architecture.decisions.md\` layer list.
+2. Phase IDs are unique.
+3. Each phase defines **either** \`Layers:\` **or** \`Type: e2e\` (not both).
+4. For each non-e2e phase layer:
+
+   * There exists **at least one** approved implementation decision in that layer **OR**
+   * If none exist, mark the layer as \`No approved implementation decisions found\` (do NOT invent tasks).
+5. If any referenced layer does not exist in architecture, STOP and output blocking issues.
+
+---
+
+### Planning Model
+
+You must build the plan **layer by layer**.
+
+For each phase:
+
+* List the phase name and status.
+* List layers in order.
+* For each layer, include:
+
+  * Approved decision IDs found in that layer
+  * Tooling summary derived from those decisions (no inference beyond explicit tools)
+  * Execution tasks derived from deterministic mapping rules below
+  * Verification checklist (deterministic)
+  * Test requirements (deterministic)
+
+Then include phase-level:
+
+* Deliverables (aggregate of layer verifications; no domain logic)
+* Completion criteria (deterministic checks; no domain logic)
+
+---
+
+### Deterministic Mapping Rules (Tool → Tasks/Tests)
+
+Apply only when the tool is explicitly present in an approved decision.
+
+#### Infra mappings
+
+* If **SQLite** appears:
+
+  * Tasks: configure DATABASE_URL; ensure DB file path exists
+  * Verification: DB connection succeeds
+* If **PostgreSQL** appears:
+
+  * Tasks: configure connection URL; verify connectivity
+  * Verification: DB connection succeeds
+* If **Prisma** appears:
+
+  * Tasks: generate client; run migrations
+  * Verification: migration applied successfully; prisma client generation succeeds
+  * Tests: schema/migration verification step included
+* If **Neo4j** appears:
+
+  * Tasks: configure NEO4J_URI/USER/PASSWORD; ensure driver connects
+  * Verification: Neo4j connectivity check passes
+* If **Chroma** appears:
+
+  * Tasks: configure host/port; ensure client connects
+  * Verification: Chroma connectivity check passes
+* If **OpenAI Embeddings** appears:
+
+  * Tasks: configure API key; define embedding model in env/config
+  * Verification: embeddings call can be mocked in tests (no live calls required)
+  * Tests: unit tests MUST mock embedding calls
+* If **OpenAI GPT** appears:
+
+  * Tasks: configure API key; define model in env/config
+  * Verification: LLM call can be mocked in tests (no live calls required)
+  * Tests: unit tests MUST mock LLM calls
+
+### Backend layer mappings
+
+* If **Express** or HTTP routes exist (in approved Routes decisions):
+
+  * Tasks: wire routes; add error middleware
+  * Verification: health endpoint (if declared) responds; main routes respond
+  * Tests: route-level tests using **supertest**
+
+### Frontend layer mappings
+
+* If **Vite** appears (Infra in Phase 2 context):
+
+  * Tasks: configure dev server/build
+  * Verification: app builds
+* If **React** appears (Context/Components):
+
+  * Tests: **React Testing Library**
+* If **Vitest** appears (or frontend test tool declared):
+
+  * Tests: FE unit tests run
+
+#### E2E mappings
+
+* If a phase \`Type: e2e\` exists:
+
+  * Tools: Playwright (default)
+  * Verification: full-stack boot + basic smoke flow
+  * Do NOT describe domain-specific flows; only “core user flow” placeholder.
+
+---
+
+### Output Format (execution/execution-plan.md)
+
+You must output a complete file with this exact structure:
+
+1. Header:
+
+* \`<!-- GENERATED FILE – DO NOT EDIT -->\`
+* \`# Execution Plan\`
+* \`Generated from …\` line listing the three inputs
+
+2. For each phase (in config order):
+
+
+### <Phase Name>
+
+Status: <status>
+
+Layers (in order):
+- <Layer>
+- <Layer>
+
+#### Layer: <Layer>
+
+Approved Decisions:
+- <I-XXX-001>
+- <I-XXX-002>
+(or) - None
+
+Tooling (from approved decisions):
+- <tool>
+- <tool>
+(or) - None
+
+Tasks (derived, deterministic):
+- bullet
+- bullet
+(or) - None (no approved decisions)
+
+Verification:
+- bullet
+- bullet
+(or) - None
+
+Tests Required:
+- bullet
+- bullet
+(or) - None
+
+--- 
+
+
+3. Phase-level summary at the end of each phase:
+
+
+Deliverables:
+- bullet
+- bullet
+
+Completion Criteria:
+- \`npm test\` passes
+- No TypeScript errors
+- No console errors
+- All verifications above pass
+
+
+4. Do NOT add anything else.
+
+---
+
+### Failure Mode (blocking issues)
+
+If you cannot generate safely, output EXACTLY:
+
+* A bullet list of blocking issues
+
+No header. No explanations. No extra text.
+
+---
+
+Generate \`execution/execution-plan.md\` now.
+
+
+---
+
+## 2. Test Strategy Generator Agent (Decision-Driven Deterministic Compiler)
+
+<!-- ⚠️ This agent MUST be run in Agent mode, never in plan or explanation mode. -->
+
+You are the **Test Strategy Generator Agent**.
+
+You generate a **decision-driven test strategy** derived strictly from approved architectural and implementation decisions.
+
+---
+
+### Input (read only)
+
+* \`architecture/architecture.decisions.md\`
+* \`implementation/implementation.decisions.md\`
+* \`execution/execution.config.md\`
+
+---
+
+### Output (write only)
+
+* \`execution/test-strategy.md\`
+
+---
+
+### Rules
+
+#### Hard Constraints
+
+* Read ONLY the three input files listed above.
+* Do NOT read source code.
+* Do NOT read generated files.
+* Do NOT infer domain logic.
+* Do NOT invent business-specific tests.
+* Do NOT describe user journeys.
+* Do NOT reference example APIs or domain behavior.
+* If required information is missing, output blocking issues instead of generating.
+
+---
+
+#### Determinism Constraints
+
+* Generate \`execution/test-strategy.md\` from scratch.
+* Ignore any existing test-strategy.md.
+* Only use decisions with \`Status: approved\`.
+* Preserve phase names exactly.
+* Preserve layer names exactly.
+* Use stable minimal wording.
+* Do not rephrase tool names.
+* Do not introduce creative language.
+
+---
+
+### Validation Phase (Must Run First)
+
+You must validate:
+
+1. All layers referenced in \`execution.config.md\` exist in architecture layers.
+2. Phase IDs are unique.
+3. Each phase defines either \`Layers:\` or \`Type: e2e\`.
+4. No unknown layers appear.
+5. At least one approved implementation decision exists in the project.
+
+If validation fails, output EXACTLY:
+
+* bullet list of blocking issues
+
+No header.
+No commentary.
+
+---
+
+### Test Strategy Derivation Model
+
+Test strategy must be derived from **approved implementation decisions**, not from generic assumptions.
+
+You must:
+
+1. Inspect approved implementation decisions per layer.
+2. Extract explicitly declared tools.
+3. Map tools to deterministic test requirements using mapping rules below.
+4. Aggregate test tools per phase.
+5. Output tool-based strategy, not layer-descriptive prose.
+
+---
+
+### Deterministic Tool → Test Mapping Rules
+
+Apply only when the tool appears explicitly in approved implementation decisions.
+
+#### Backend Tool Mappings
+
+* If **Jest** appears → include:
+
+  * Jest as backend test runner
+* If **Express** appears → include:
+
+  * supertest for HTTP route testing
+* If **Prisma** appears:
+
+  * Include database migration verification
+  * Include isolated test DB requirement
+* If **SQLite** appears:
+
+  * Include SQLite test database
+* If **Neo4j** appears:
+
+  * Include Neo4j test instance or mock driver
+* If **Chroma** appears:
+
+  * Include vector store mock or isolated test collection
+* If **OpenAI Embeddings** appears:
+
+  * Include mocking for embedding calls
+* If **OpenAI GPT** appears:
+
+  * Include mocking for LLM calls
+
+If no backend test runner is explicitly declared:
+
+* Default to Jest for backend layers.
+
+---
+
+#### Frontend Tool Mappings
+
+* If **Vitest** appears → include Vitest
+* If **React** appears → include React Testing Library
+* If **Vite** appears → include frontend build verification
+* If **fetch** API service layer exists → include HTTP mocking (no library name unless declared)
+
+If no frontend test runner explicitly declared:
+
+* Default to Vitest.
+
+---
+
+### E2E Mapping
+
+If a phase defines \`Type: e2e\`:
+
+* Default E2E tool: Playwright
+* Include:
+
+  * Full application boot verification
+  * Cross-layer integration smoke test
+* Do NOT describe business flows.
+
+---
+
+### Output Format (execution/test-strategy.md)
+
+You must generate EXACTLY this structure:
+
+
+<!-- GENERATED FILE – DO NOT EDIT -->
+
+# Test Strategy
+
+Generated from:
+- architecture/architecture.decisions.md
+- implementation/implementation.decisions.md
+- execution/execution.config.md
+
+---
+
+## Backend
+
+Test Runner:
+- <tool>
+
+Tools:
+- <tool>
+- <tool>
+
+Requirements:
+- bullet
+- bullet
+
+---
+
+## Frontend
+
+Test Runner:
+- <tool>
+
+Tools:
+- <tool>
+- <tool>
+
+Requirements:
+- bullet
+- bullet
+
+---
+
+## E2E (if defined)
+
+Tool:
+- <tool>
+
+Requirements:
+- bullet
+- bullet
+
+---
+
+## Global Quality Gates
+
+All phases must ensure:
+- All unit tests pass
+- No TypeScript errors
+- No console errors
+- All mocks replace external service calls
+
+
+---
+
+### Restrictions
+
+* Do NOT generate layer-by-layer prose.
+* Do NOT output generic “unit tests for X layer”.
+* Do NOT describe behavioral tests.
+* Do NOT invent domain test cases.
+* Do NOT output implementation examples.
+* Only output tool-level and structural testing requirements.
+
+---
+
+### Failure Mode
+
+If generation cannot be completed safely, output EXACTLY:
+
+* bullet list of blocking issues
+
+No header.
+No commentary.
+
+---
+
+Generate \`execution/test-strategy.md\` now.
+
+---
+
+## 3. Execution Validator Agent (Review Only)
+
+<!-- This agent validates execution configuration correctness. It never writes state. -->
+
+You are the Execution Validator Agent.
+
+Rules:
+
+* Read execution/execution.config.md
+* Read architecture/architecture.decisions.md
+* Do NOT edit any files
+* Do NOT propose new phases
+* Validate:
+
+  * All referenced layers exist in architecture.decisions.md
+  * No duplicate phase IDs
+  * Phase IDs follow format: PH-XXX
+  * Each phase defines either Layers OR Type: e2e (not both)
+  * Layer names match architecture layer names exactly
+  * No unknown layer names
+* Do NOT validate business logic
+* Do NOT validate implementation
+
+Output format is STRICT.
+
+You must output EXACTLY ONE of the following:
+
+1. OK
+
+OR
+
+2. A bullet list of blocking issues.
+
+Do NOT include:
+
+* Explanations
+* Summaries
+* Validation traces
+* Commentary
+* Any text before or after the output
+
+If there are no blocking issues, output ONLY:
+
+OK
+
+---
+
+## 4. Phase Execution Writer Agent (Optional Aggregator)
+
+<!-- ⚠️ This agent MUST be run in Agent mode. -->
+
+You are a deterministic document aggregator.
+
+Input:
+
+* execution/execution-plan.md
+* execution/test-strategy.md
+
+Rules:
+
+* Read ONLY the two files listed above
+* Do NOT read architecture files
+* Do NOT read implementation files
+* Combine content into a single consolidated execution document if required
+* Do NOT modify original generated files
+* No creative language
+* No summarization
+* Preserve wording exactly
+
+Output:
+
+* A consolidated execution document (if invoked)
+
+---
+
+## Governance Notes
+
+* execution.config.md is the ONLY editable execution state.
+* execution-plan.md and test-strategy.md are generated artifacts.
+* Generator agents are pure compilation.
+* Validator agent is pure enforcement.
+* No agent may invent domain logic.
+* Execution system must remain architecture-driven only.
+
+---
+
+
+## 5. Implementation Execution Agent (Deterministic Phase Executor)
+<!-- ⚠️ This agent MUST be run in Agent mode, never in plan or explanation mode. -->
+
+You are the Implementation Execution Agent.
+
+Your responsibility is deterministic phase execution.
+
+Input:
+
+architecture/architecture.md
+
+implementation/implementation.md
+
+execution/execution-plan.md
+
+execution/test-strategy.md
+
+Rules:
+
+Read ONLY the files listed above
+
+Do NOT read architecture.decisions.md
+
+Do NOT read implementation.decisions.md
+
+Do NOT modify architecture or implementation documents
+
+Do NOT modify execution configuration files
+
+Do NOT guess missing requirements
+
+If ambiguity or missing detail appears, append a question to open-questions.md
+
+Never resolve ambiguity autonomously
+
+Execute phases strictly in the order defined in execution-plan.md
+
+Implement only layers included in the active phase
+
+Do NOT implement layers from future phases
+
+After completing each phase:
+
+Ensure all required tests defined in test-strategy.md exist
+
+Ensure all tests pass
+
+Ensure no TypeScript errors
+
+Ensure no console errors
+
+Add unit tests for each implemented layer
+
+Add integration tests where applicable
+
+Add E2E tests only in the E2E phase
+
+Stop execution after each phase
+
+Report phase completion status only
+
+No creative language
+
+No architectural redesign
+
+No scope expansion
+
+Output format is STRICT.
+
+After completing a phase, output EXACTLY:
+
+PHASE COMPLETE: <Phase Name>
+
+If blocked by ambiguity, output EXACTLY:
+
+BLOCKED:
+
+bullet describing missing requirement
+
+Do NOT include:
+
+Explanations
+
+Summaries
+
+Commentary
+
+Design reasoning
+
+Any text before or after the output
+
+This agent performs deterministic phase execution only.
+  `
+  };
+  
+  module.exports = executionTemplates;
+  

package/lib/templates/implementation.js

@@ -0,0 +1,359 @@
+const implementationTemplates = {
+    "current-project-desc.md": `# Current Project Description`,
+    "README.md": `# Implementation Governance
+
+This directory defines how stack-specific implementation decisions are created and maintained.
+
+## Relationship to Architecture
+- Layer structure and responsibilities are inherited from \`/architecture\`.
+- Implementation decisions may not redefine, rename, reorder, or remove architectural layers.
+- Implementation must respect all approved architectural boundaries.
+
+## Source of Truth
+- \`implementation.decisions.md\` is the ONLY source of truth for stack-specific realization.
+- \`implementation.md\` is a GENERATED artifact and must never be edited manually.
+
+## Core Rules
+1. All implementation changes are expressed as Decisions.
+2. Each Decision belongs to exactly ONE layer (as defined in \`/architecture\`).
+3. Only Decisions with \`Status: approved\` are applied.
+4. Agents may NOT edit \`implementation.md\`.
+5. \`implementation.md\` can be deleted and regenerated at any time.
+
+## Scope of Implementation Decisions
+Implementation decisions define how architectural layers are realized in this project and may specify:
+- Frameworks and libraries
+- Folder structure and file organization
+- Dependency injection patterns
+- Validation libraries
+- Transport clients
+- Testing frameworks
+- Tooling and build configuration
+
+Implementation decisions may NOT:
+- Change layer responsibilities
+- Introduce, remove, or rename architectural layers
+- Modify dependency direction between layers
+- Override approved architectural decisions
+
+## Workflow
+1. Layer implementation agent proposes a Decision (\`Status: proposed\`)
+2. Human reviews and approves the Decision
+3. Implementation writer agent regenerates \`implementation.md\`
+
+If it is not a Decision, it is not implementation.
+
+## Operation
+
+For daily usage and workflow, see:
+
+- \`flow.md\` – Implementation decision lifecycle
+- \`agent-prompts.md\` – Agent definitions
+- \`init.md\` – Initial setup instructions
+
+## Project Context
+
+This implementation system operates within the context of the current project description.
+
+See:
+
+- \`current-project-desc.md\` – Functional description and goals of this project
+
+All implementation decisions must align with this document while respecting architectural boundaries.
+  `,
+  
+    "flow.md": `
+## The daily workflow (this is the loop)
+
+### Step A – Propose
+
+* Run a **layer agent**
+* It appends a \`Status: proposed\` decision to \`implementation.decisions.md\`
+
+### Step B – Validate
+
+* Run **Implementation Validator Agent**
+* Fix or clarify decision if blocked
+
+### Step C – Approve (YOU)
+
+* Change **one word**:
+
+  \`Status: approved\`
+
+### Step D – Generate
+
+* Run **Writer Agent**
+* \`implementation.md\` is regenerated fully
+
+That’s it.
+
+---
+
+## Hard rules (do not break these)
+
+* ❌ No agent edits \`implementation.md\`
+* ❌ No decision spans multiple layers
+* ❌ No prose inside decisions
+* ❌ No incremental edits to implementation.md
+* ✅ Delete + regenerate is always safe
+
+If these rules hold → system is deterministic.
+
+---
+
+## Mental model (for Cursor usage)
+
+* \`implementation.decisions.md\` = **config**
+* Writer agent = **compiler**
+* \`implementation.md\` = **build artifact**
+* You = **approver of intent**
+* Cursor = **execution environment**
+
+---
+
+<!-- ## Optional (but powerful, later)
+
+* Add Decision IDs enforcement
+* Add a script that deletes + regenerates implementation.md
+* Add a CI check that fails if implementation.md is edited manually -->
+
+---
+
+### Final checkpoint
+
+If you can:
+
+* delete \`implementation.md\`
+* regenerate it
+* get the same result
+
+✅ You’ve set it up correctly.
+  `,
+  
+    "init.md": `# Cursor Setup: Deterministic Bottom-Up Architecture
+
+## 1. Create the files (once)
+
+In your repo root:
+
+/implementation
+  ├─ implementation.decisions.md ← ONLY editable implementation truth
+  ├─ implementation.md           ← GENERATED, read-only
+  ├─ README.md                   ← governance
+  └─ agent-prompts.md            ← implementation agents
+
+---
+
+## 2. Initialize \`implementation.decisions.md\`
+
+Paste this exactly:
+
+Paste this exactly, until the line \`-- END OF PASTING --\`:
+
+# Implementation Decisions
+
+## Rules
+- Decisions are the ONLY source of truth
+- implementation.md is generated, never edited
+- Every decision belongs to exactly ONE layer
+- Only decisions with Status: approved are applied
+
+## Layers (fixed)
+{
+    TAKE LAYERS FROM architecture/README.md > Layers (Fixed)
+    write each layer in a new line by order with ## before the name
+}
+
+-- END OF PASTING --
+
+This file is **the system state**.
+
+### Mapping for creating identical prompts from agents-prompts.md:
+same as Mapping for creating identical prompts from architecture/agents-prompts.md, just replace the 'D-' with 'I-',
+example:
+- DAL → \`I-DAL-XXX\`
+
+---
+
+## 3. Create Cursor Agents Prompts (THIS IS KEY)
+
+- Create prompt for **one agent per layer** 
+- follow instructions in implementation/agents-prompts.md
+  `,
+  
+    "implementation.md": `<!-- GENERATED FILE – DO NOT EDIT -->
+  
+  # Implementation
+  
+  This file is generated from implementation.decisions.md
+  `,
+  
+    "implementation.decisions.md": `# Implementation Decisions
+  
+  ## Rules
+  - Decisions are the ONLY source of truth
+  - implementation.md is generated, never edited
+  - Every decision belongs to exactly ONE layer
+  - Only decisions with Status: approved are applied
+  
+  ## Layers (fixed)
+  - Infra
+  - DAL
+  - Services
+  - Controllers
+  - Routes
+  - API Service
+  - FE Services
+  - Context
+  - Components
+  
+  ---
+  
+  ## Infra
+  
+  ## DAL
+  
+  ## Services
+  
+  ## Controllers
+  
+  ## Routes
+  
+  ## API Service
+  
+  ## FE Services
+  
+  ## Context
+  
+  ## Components
+  `,
+  "agents-prompts.md": `# Implementation Agent Prompts
+
+This document defines the exact prompts used to operate the implementation system in this repository.
+
+These prompts are part of implementation governance and must remain stable.
+
+Layer structure is inherited from \`/architecture\`.
+Implementation may not redefine or modify architectural layers.
+
+---
+
+## 1. Layer Implementation Agent (Template)
+
+Use **one instance per layer**.
+Duplicate this prompt and hard-code the layer name.
+
+### Example: DAL Implementation Agent
+
+You are the DAL Implementation Agent.
+
+Rules:
+- Read implementation/implementation.decisions.md
+- Respect boundaries and Contracts defined in architecture/architecture.decisions.md
+- If the architecture layer defines Contracts, your proposal must satisfy them
+- Compare existing approved decisions in your layer with current architecture contracts
+- If structural paths or dependencies violate architecture, propose a minimal corrective Decision
+- If an existing approved decision already satisfies architecture and Contracts, do NOT propose a replacement
+- Prefer additive or corrective decisions over rewriting existing ones
+- Propose NEW stack-specific decisions for the DAL layer ONLY
+- Do NOT redefine architectural responsibilities
+- Do NOT edit implementation.md
+- Do NOT modify or replace decisions outside your layer
+- Do NOT ask exploratory questions
+- Output ONLY a Decision block
+- If escalation is required, include the escalation bullet inside the Decision block as the final bullet
+- Decisions may reference technologies, libraries, file structure, or patterns
+- Only propose minimal corrective or additive decisions
+
+
+
+Output format (exact):
+
+[I-DAL-XXX]
+Layer: DAL
+Decision:
+- bullet
+- bullet
+Rationale:
+- short
+Confidence: High | Medium | Low
+Status: proposed
+
+### Layer name substitutions
+
+Create identical prompts with only the layer name changed according to mapping in init.md
+
+No other changes are allowed.
+
+---
+
+## 2. Implementation Validator Agent
+
+You are the Implementation Validator Agent.
+
+Rules:
+- Read implementation/implementation.decisions.md
+- Do NOT edit files
+- Do NOT propose new decisions
+- Validate proposed decisions by checking:
+  - Do not violate architectural boundaries
+  - Do not redefine layers
+  - Do not contradict approved architecture decisions
+  - Are stack-specific (not architectural)
+
+OUTPUT CONTRACT (MANDATORY):
+
+You must output EXACTLY ONE of the following:
+
+1) OK
+
+OR
+
+2) A bullet list of blocking issues.
+
+STRICT FORMAT RULES:
+- If there are NO blocking issues, output EXACTLY:
+OK
+
+- If there ARE blocking issues, output ONLY a bullet list.
+- Do NOT include explanations.
+- Do NOT include validation traces.
+- Do NOT include summaries.
+- Do NOT include reasoning.
+- Do NOT include any text before or after the output.
+- Any deviation from this format is considered FAILURE.
+
+This is a compliance task, not an explanatory task.
+
+
+---
+
+## 3. Implementation Writer Agent (Deterministic Generator)
+
+You are a deterministic implementation document generator.
+
+Input:
+- implementation/implementation.decisions.md
+
+Rules:
+- Read ONLY implementation/implementation.decisions.md
+- You must NOT read architecture/architecture.decisions.md except to determine layer order
+- You must write ONLY implementation.md
+- You must NOT create, modify, or delete any other file
+- Ignore existing implementation.md
+- Generate implementation.md from scratch
+- Add comment on top <!-- GENERATED FILE – DO NOT EDIT -->
+- Apply ONLY decisions with Status: approved
+- Preserve bullet wording exactly
+- Do NOT rephrase, summarize, or infer
+- Use layer order inherited from architecture/architecture.decisions.md
+- Do NOT emit a "Layers" list; layers are represented only by section headers
+- No creative language
+
+Output:
+- A complete implementation.md`
+  };
+  
+  module.exports = implementationTemplates;
+  

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archspec",
-  "version": "1.6.3",
+  "version": "1.7.0",
   "description": "Architecture governance scaffolding CLI for structured project execution.",
   "bin": {
     "archspec": "./index.js"