archspec 1.0.2 → 1.3.0

package/index.js

@@ -1,32 +1,11 @@
 #!/usr/bin/env node
 
-const fs = require("fs");
-const path = require("path");
+const init = require("./lib/init");
 
 const command = process.argv[2];
 
 if (command === "init") {
   init();
 } else {
-  console.log("Usage: shesdev-hello-arch init");
-}
-
-function init() {
-  createFolder("architecture");
-  createFolder("governance");
-  createFolder("implementation");
-  createFolder("execution");
-
-  console.log("Governance structure initialized.");
-}
-
-function createFolder(name) {
-  const dirPath = path.resolve(process.cwd(), name);
-
-  if (!fs.existsSync(dirPath)) {
-    fs.mkdirSync(dirPath);
-    console.log(`Created folder: ${name}`);
-  } else {
-    console.log(`Folder already exists: ${name}`);
-  }
+  console.log("Usage: archspec init");
 }

package/lib/createFolderWithFiles.js

@@ -0,0 +1,22 @@
+const fs = require("fs");
+const path = require("path");
+
+function createFolderWithFiles(folderName, files) {
+  const folderPath = path.resolve(process.cwd(), folderName);
+
+  if (!fs.existsSync(folderPath)) {
+    fs.mkdirSync(folderPath);
+    console.log(`Created folder: ${folderName}`);
+  }
+
+  Object.entries(files).forEach(([fileName, content]) => {
+    const filePath = path.join(folderPath, fileName);
+
+    if (!fs.existsSync(filePath)) {
+      fs.writeFileSync(filePath, content);
+      console.log(`Created file: ${folderName}/${fileName}`);
+    }
+  });
+}
+
+module.exports = createFolderWithFiles;

package/lib/init.js

@@ -0,0 +1,9 @@
+const createFolderWithFiles = require("./createFolderWithFiles");
+const architectureTemplates = require("./templates/architecture");
+
+function init() {
+  createFolderWithFiles("architecture", architectureTemplates);
+  console.log("Architecture folder initialized.");
+}
+
+module.exports = init;

package/lib/templates/architecture.js

@@ -0,0 +1,380 @@
+const architectureTemplates = {
+    "README.md": `# Architecture Governance
+  
+  This directory defines how architecture is created and maintained.
+  
+  ## Source of Truth
+  - \`architecture.decisions.md\` is the ONLY source of truth.
+  - \`architecture.md\` is a GENERATED artifact and must never be edited manually.
+  
+  ## Core Rules
+  1. All architectural changes are expressed as Decisions.
+  2. Each Decision belongs to exactly ONE layer.
+  3. Only Decisions with \`Status: approved\` are applied.
+  4. Agents may NOT edit \`architecture.md\`.
+  5. \`architecture.md\` can be deleted and regenerated at any time.
+  
+  ## Layers (Fixed)
+  The system uses a bottom-up, layered architecture:
+  
+  1. Infra
+  2. DAL
+  3. Services
+  4. Controllers
+  5. Routes
+  6. API Service
+  7. FE Services
+  8. Context
+  9. Components
+  
+  These layers are fixed and must not be renamed or reordered.
+  
+  ## Workflow
+  1. Layer agent proposes a Decision (\`Status: proposed\`)
+  2. Human reviews and approves the Decision
+  3. Writer agent regenerates \`architecture.md\` from decisions
+  
+  If it is not a Decision, it is not architecture.
+  
+  ## Operation
+  
+  For daily usage and workflow, see:
+  
+  - \`flow.md\` – Implementation decision lifecycle
+  - \`agent-prompts.md\` – Agent definitions
+  - \`init.md\` – Initial setup instructions
+  `,
+  
+    "flow.md": `## The daily workflow (this is the loop)
+  
+  ### Step A – Propose
+  
+  * Run a **layer agent**
+  * It appends a \`Status: proposed\` decision to \`architecture.decisions.md\`
+  
+  ### Step B – Validate
+  
+  * Run **Architect Agent**
+  * Fix or clarify decision if blocked
+  
+  ### Step C – Approve (YOU)
+  
+  * Change **one word**:
+  
+    Status: approved
+  
+  ### Step D – Generate
+  
+  * Run **Writer Agent**
+  * \`architecture.md\` is regenerated fully
+  
+  That’s it.
+  
+  ---
+  
+  ## Hard rules (do not break these)
+  
+  * ❌ No agent edits \`architecture.md\`
+  * ❌ No decision spans multiple layers
+  * ❌ No prose inside decisions
+  * ❌ No incremental edits to architecture.md
+  * ✅ Delete + regenerate is always safe
+  
+  If these rules hold → system is deterministic.
+  
+  ---
+  
+  ## Mental model (for Cursor usage)
+  
+  * \`architecture.decisions.md\` = config
+  * Writer agent = compiler
+  * \`architecture.md\` = build artifact
+  * You = approver of intent
+  * Cursor = execution environment
+  
+  ---
+  
+  ### Final checkpoint
+  
+  If you can:
+  
+  * delete \`architecture.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:
+
+/architecture
+  ├─ architecture.decisions.md   ← ONLY editable truth
+  ├─ architecture.md             ← GENERATED, read-only
+  └─ README.md                   ← rules 
+
+---
+
+## 2. Initialize \`architecture.decisions.md\`
+
+Paste this exactly, until the line \`-- END OF PASTING --\`:
+
+
+# Architecture Decisions
+
+## Rules
+- Decisions are the ONLY source of truth
+- architecture.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
+
+-- END OF PASTING --
+
+This file is **the system state**.
+
+Mapping for creating identical prompts from agents-prompts.md:
+- DAL → \`D-DAL-XXX\`
+- Services → \`D-SVC-XXX\`
+- Controllers → \`D-CTL-XXX\`
+- Routes → \`D-RTE-XXX\`
+- API Service → \`D-API-XXX\`
+- FE Services → \`D-FES-XXX\`
+- Context → \`D-CTX-XXX\`
+- Components → \`D-CMP-XXX\`
+
+---
+
+## 3. Make \`architecture.md\` read-only (discipline rule)
+
+* Never manually edit it
+* Treat it like \`dist/\` or \`build/\`
+* If needed, add a comment at the top:
+<!-- GENERATED FILE – DO NOT EDIT -->
+
+---
+
+## 4. Create Cursor agents (THIS IS KEY)
+
+- Create **one agent per layer** 
+- follow instructions in agents-prompts.md
+  `,
+  
+    "agents-prompts.md": `# Architecture Agent Prompts
+  
+  This document defines the **exact prompts** used to operate the architecture system in this repository.
+  
+  These prompts are part of the architecture governance.
+  They must remain stable and should not be casually modified.
+  
+  ---
+  
+  ## 1. Layer Architecture Agent (Template)
+  
+  Use **one instance per layer**.
+  Duplicate this prompt and hard-code the layer name.
+  
+  ### Example: DAL Architecture Agent
+  
+  You are the DAL Architecture Agent.
+  
+  Rules:
+  - Read architecture/architecture.decisions.md
+  - Propose NEW decisions for the DAL layer ONLY
+  - Do NOT write prose
+  - Do NOT edit architecture.md
+  - Do NOT modify or replace decisions outside your layer
+  - Output ONLY a Decision block.
+  - If escalation is required, include the escalation bullet inside the Decision block as the final bullet.
+  - Each decision must be minimal and explicit
+  - If two decisions describe the same boundary, merge them 
+  - Prefer definition over enforcement
+  - If the decision feels "obvious", defer it
+  - If structural invariants are required, include a Contracts section.
+  - Contracts define machine-checkable architectural invariants.
+  - Contracts must be explicit key: value pairs.
+  - Contracts must not contain prose or explanations.
+  - Contracts must be enforceable by simple structural matching.
+  
+  Output format (exact):
+  
+  [D-DAL-XXX]
+  Layer: DAL
+  Decision:
+  - bullet
+  - bullet
+  Contracts (optional, machine-checkable invariants):
+  - key: value
+  - key: value
+  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. Architect Validator Agent (Review Only)
+  
+  <!-- This agent validates correctness and scope. It never writes state. -->
+  
+  You are the Architect Validator Agent.
+  
+  Rules:
+  
+  - Read architecture/architecture.decisions.md ONLY
+  - Do NOT edit any files
+  - Do NOT propose new decisions
+  - Validate proposed decisions by checking:
+      - Layer correctness
+      - Conflicts with approved decisions
+      - Cross-layer violations
+      - Internal contradictions
+      - Ambiguous in bullets
+  - If a Contracts section exists, treat it as part of the decision and validate that:
+    - Contracts are explicit key-value pairs
+    - Contracts are layer-scoped
+    - Contracts do not contradict other approved decisions
+  
+  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
+  - Decision reviews
+  - Any text before or after the output
+  
+  If there are no blocking issues, output ONLY:
+  
+  OK
+  
+  ---
+  
+  ## 3. Writer Agent (Deterministic Generator)
+  
+  <!-- ⚠️ This agent MUST be run in **Agent mode**, never in plan or explanation mode. -->
+  
+  You are a deterministic document generator.
+  
+  Input:
+  - architecture.decisions.md
+  
+  Rules:
+  - Read ONLY architecture/architecture.decisions.md
+  - You must NOT read implementation/implementation.decisions.md
+  - You must write ONLY architecture.md
+  - You must NOT create, modify, or delete any other file
+  - Ignore any existing architecture.md
+  - Generate architecture.md from scratch
+  - Apply ONLY decisions with Status: approved
+  - Preserve bullet wording exactly
+  - Do NOT rephrase, summarize, or infer
+  - Sort layers in fixed order
+  - Use fixed layer order as specified in architecture/architecture.decisions.md
+  - Do NOT emit a "Layers" list; layers are represented only by section headers
+  - No creative language
+  
+  Output:
+  - A complete architecture.md file
+  
+  <!-- This agent is **pure compilation**. -->
+  
+  ---
+  `,
+  
+    "architecture.decisions.md": `# Architecture Decisions
+  
+  ## Rules
+  - Decisions are the ONLY source of truth
+  - architecture.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
+  `,
+  
+    "architecture.md": `<!-- GENERATED FILE – DO NOT EDIT -->
+  
+  # Architecture
+  
+  This file is generated from architecture.decisions.md
+  `
+  };
+
+  module.exports = architectureTemplates;

package/package.json

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