@zik000/archai 0.2.1 → 0.2.2

package/README.md

@@ -4,9 +4,7 @@
 
 Archai scaffolds a multi-agent system that plans before it codes, validates before it implements, and tests before it ships. One command sets it up. Claude Code does the rest.
 
-```
-Plan → Implement → Finalize
-```
+![Three-Phase Architecture](diagram.jpg)
 
 [Join our Discord](https://discord.gg/J3wgDb4YJv)
 
@@ -20,6 +18,8 @@ Without structure, AI assistants jump straight to code — skipping analysis, mi
 2. **Implementation Loop** — Code, test, review (only after you approve the plan)
 3. **Finalization** — Quality checks, cleanup, commit, push, CI verification
 
+Agents **learn across sessions** through a persistent knowledge base — decisions, constraints, patterns, and gotchas are recorded and searched before every new task.
+
 You stay in control with approval gates between phases. Or use **critical review mode** to let a separate AI session review the plan automatically.
 
 ## Quick Start
@@ -62,21 +62,30 @@ archai generate          # Generate project-specific specialist agents
 
 ## How to Use
 
-### The Main Workflow
+### Step 1: Define Your Task
 
-For any non-trivial task, use `iteration-controller`. It orchestrates the entire three-phase workflow:
+Write a clear description of what you want done. Drop it into a task file:
 
 ```
-> Use iteration-controller for: [describe your task]
+.tasks/inbox/add-user-auth.md
 ```
 
-**What happens:**
-1. `deep-analyst` analyzes your codebase and creates an implementation plan
-2. `plan-validator` challenges the plan and finds gaps
-3. `tdd-designer` designs tests before any code is written
-4. **You review and approve the plan** (or request revisions)
-5. `implementation-agent` builds it, `code-reviewer` verifies it
-6. `finalization-agent` runs quality checks, commits, and pushes
+Or just describe it directly in Claude Code. The more specific you are, the better the agents perform.
+
+### Step 2: Feed It to the Agent System
+
+Open Claude Code and hand the task to `iteration-controller`:
+
+```
+> Use iteration-controller for: add user authentication with JWT
+```
+
+That's it. The agent system takes over:
+
+1. **Planning** — `deep-analyst` studies your codebase, `plan-validator` challenges the plan, `tdd-designer` writes tests first. This iterates 2-4 times until the plan is solid.
+2. **Your approval** — The workflow stops and presents the plan. You APPROVE, REVISE, or REJECT.
+3. **Implementation** — `implementation-agent` builds it, `code-reviewer` verifies it. Iterates until tests pass.
+4. **Finalization** — `finalization-agent` runs quality checks, cleans up, commits, and pushes.
 
 ### Critical Review Mode
 
@@ -103,15 +112,15 @@ For small, obvious changes (typos, renames, config tweaks, 1-3 files):
 
 No planning docs, no approval gates. If the change turns out to be bigger than expected, it tells you to use `iteration-controller` instead.
 
-### Task Management
+### Batch Tasks
 
-For managing multiple tasks across an epic:
+For managing multiple tasks across an epic, drop them all into `.tasks/inbox/` and run:
 
 ```
 > Use task-orchestrator for: work through the tasks in .tasks/inbox/
 ```
 
-It claims tasks, creates branches, spawns the workflow, and tracks progress.
+It claims tasks one by one, creates branches, spawns the full workflow for each, and tracks progress.
 
 ### Standalone Agents
 
@@ -186,7 +195,7 @@ your-project/
 │   ├── plans/           # Approved implementation plans
 │   ├── state/           # Working state (gitignored)
 │   └── version.json     # Version tracking for smart updates
-├── .knowledge/          # Project context, decisions, learnings
+├── .knowledge/          # Persistent knowledge base (decisions, constraints, patterns, learnings)
 ├── .tasks/              # Task inbox, epics, review, done
 ├── archai.config.md     # Project configuration
 ├── CLAUDE.md            # Agentic behavior guidelines (auto-generated)

package/dist/scaffold/create-structure.js

@@ -15,8 +15,8 @@ const FOLDERS = [
     '.knowledge/context',
     '.knowledge/decisions',
     '.knowledge/learnings',
-    '.knowledge/planning',
-    '.knowledge/status',
+    '.knowledge/constraints',
+    '.knowledge/patterns',
     // Task management
     '.tasks/inbox',
     '.tasks/done',

package/dist/scaffold/create-structure.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-structure.js","sourceRoot":"","sources":["../../src/scaffold/create-structure.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"create-structure.js","sourceRoot":"","sources":["../../src/scaffold/create-structure.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zik000/archai",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Multi-agent AI development workflow setup for any project",
   "keywords": [
     "claude",

package/templates/core-agents/code-reviewer.md

@@ -84,6 +84,38 @@ Write to `.claude/state/code_review.md`:
 [APPROVED for merge / NEEDS CHANGES before merge / REJECTED - reason]
 ```
 
+## Knowledge Base — Write
+
+After completing your review, perform the following knowledge capture steps:
+
+1. **Read signals**: Check `.claude/state/knowledge_signals.md` for signals accumulated during the implementation phase.
+
+2. **Review your own findings**: Identify patterns established, gotchas discovered, things that failed before working, conventions set during implementation, and workarounds for non-obvious issues.
+
+3. **Search before write**: For each knowledge-worthy item, search `.knowledge/` for existing entries on the same topic using Grep with relevant keywords. If overlap exists with the same conclusion, skip. If overlap exists with a different conclusion, supersede the old entry (set its Status to `superseded`, add `## Superseded By` with the new filename). If no overlap, create a new entry.
+
+4. **Write entries**: Create entries in the appropriate category (`decisions/`, `constraints/`, `patterns/`, `learnings/`) using this format:
+
+```markdown
+# [Clear, Descriptive Title]
+
+**Status**: active
+**Date**: YYYY-MM-DD
+**Tags**: keyword1, keyword2, keyword3
+
+## What
+[The decision, constraint, pattern, or learning. 1-3 clear sentences.]
+
+## Why
+[The reasoning. What problem does this solve? 1-3 sentences.]
+```
+
+Filename format: `{YYYYMMDD}-{HHMMSS}-{slug}.md`. Focus on what a future agent would need to know to avoid the same mistakes or follow the same patterns.
+
+5. **Clear signals**: After processing, clear the processed signals from `.claude/state/knowledge_signals.md`.
+
+6. **Check CLAUDE.md**: If any entry supersedes an older one, check if `CLAUDE.md` or `archai.config.md` references the superseded decision. If so, flag it for update.
+
 ## Remember
 
 Be thorough but fair. Every issue must be specific and actionable — include file, line, and suggested fix.

package/templates/core-agents/deep-analyst.md

@@ -20,6 +20,39 @@ Read project context from:
 - `.knowledge/context/project-description.md` - Project overview and architecture
 - `archai.config.md` - Tech stack, key files, and commands
 
+## Knowledge Base
+
+**Read**: Before making decisions, search `.knowledge/` for relevant prior decisions, constraints, patterns, and learnings. Use Grep with 2-3 keywords from the current task. Read full entries for anything relevant. Surface relevant entries in your output. If you find conflicts between your proposed approach and existing knowledge, flag them explicitly — do not silently override prior decisions.
+
+**Signal**: During your work, if you make or discover a significant decision, constraint, or clarification — append a brief signal to `.claude/state/knowledge_signals.md` using this format:
+
+```markdown
+## Signal: [brief description]
+**Type**: decision | constraint | pattern | learning
+**Detail**: [1-2 sentences about what was decided/discovered and why]
+**Source**: deep-analyst, Phase 1
+```
+
+**Write (final planning iteration only)**: At the end of the planning phase, convert accumulated signals into formal knowledge entries. For each: search `.knowledge/` for existing entries on the same topic (search-before-write). If overlap exists with the same conclusion, skip. If overlap exists with a different conclusion, supersede the old entry. If no overlap, create a new entry in the appropriate category (`decisions/`, `constraints/`, `patterns/`, `learnings/`) using this format:
+
+```markdown
+# [Clear, Descriptive Title]
+
+**Status**: active
+**Date**: YYYY-MM-DD
+**Tags**: keyword1, keyword2, keyword3
+
+## What
+[The decision, constraint, pattern, or learning. 1-3 clear sentences.]
+
+## Why
+[The reasoning. What problem does this solve? What would go wrong without it? 1-3 sentences.]
+```
+
+Filename format: `{YYYYMMDD}-{HHMMSS}-{slug}.md`. Entries must be human-readable — write for a developer browsing the repo, not just for agents.
+
+**Conflict Resolution**: If you find two knowledge entries that contradict each other, determine which is authoritative (newer, more specific, or whose `Affects` files are less modified). If unclear, escalate to the user — do not guess. Present both entries and ask which to follow.
+
 ## Analysis Protocol
 
 ### Phase 1: Dependency Mapping (MANDATORY)
@@ -147,6 +180,8 @@ Immediately flag these situations:
 - Framework-specific behavior concerns
 - Performance concerns
 - Security implications
+- **Knowledge conflicts** — two entries contradict and source of truth is unclear
+- **Existing entry blocks approach** — prior decision prevents the proposed approach
 
 ## Remember
 

package/templates/core-agents/finalization-agent.md

@@ -18,7 +18,28 @@ Read `.claude/state/task_anchor.md` and verify:
 - [ ] All constraints are respected
 - [ ] Success definition is achieved
 
-### Step 2: Quality Checks
+### Step 2: Knowledge Base — Verify
+
+Before committing, verify that any `.knowledge/` entries created during this task have valid format:
+
+1. **Format check**: Each entry must contain these required sections:
+   - `# [Title]` (H1 heading)
+   - `**Status**: active | superseded`
+   - `**Date**: YYYY-MM-DD`
+   - `**Tags**: keyword1, keyword2`
+   - `## What` section
+   - `## Why` section
+
+2. **Filename check**: Entry filenames must follow `{YYYYMMDD}-{HHMMSS}-{slug}.md` format.
+
+3. **Supersession check**: If any entry has `**Status**: superseded`, verify it has a `## Superseded By` section with the replacement entry filename.
+
+4. **CLAUDE.md sync check**: If any entry supersedes an older one, check if `CLAUDE.md` or `archai.config.md` references the superseded decision. If so, flag it for the user:
+   > "Note: CLAUDE.md references [old pattern]. Knowledge entry [new entry] supersedes this. CLAUDE.md may need updating."
+
+5. **Commit knowledge**: Include all `.knowledge/` entries in the commit alongside code changes.
+
+### Step 3: Quality Checks
 
 Run commands from `archai.config.md`:
 
@@ -30,13 +51,13 @@ Run commands from `archai.config.md`:
 
 All must pass before proceeding. If they fail, fix issues and re-run.
 
-### Step 3: Cleanup
+### Step 4: Cleanup
 
 - Archive task state to `.claude/state/archived/{task-id}/`
 - Remove temporary files from `.agents/`
 - Ensure `.gitkeep` files remain
 
-### Step 4: Commit
+### Step 5: Commit
 
 ```bash
 git add [specific files from the task]
@@ -53,7 +74,7 @@ EOF
 
 Types: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`
 
-### Step 5: Push
+### Step 6: Push
 
 ```bash
 git push origin [branch-name]
@@ -61,14 +82,14 @@ git push origin [branch-name]
 
 If push fails: `git pull --rebase origin [branch-name]`, resolve conflicts, push again.
 
-### Step 6: Wait for CI/CD
+### Step 7: Wait for CI/CD
 
 ```bash
 gh run list --branch [branch-name] --limit 1
 gh run watch [run-id]
 ```
 
-If CI fails: report which checks failed, wait for user instruction, then repeat steps 4-6 after fix.
+If CI fails: report which checks failed, wait for user instruction, then repeat steps 5-7 after fix.
 
 ## Output Format
 
@@ -79,6 +100,12 @@ If CI fails: report which checks failed, wait for user instruction, then repeat
 - Acceptance criteria: [X/Y] met
 - Constraints respected: YES/NO
 
+## Knowledge Base Verification
+- Entries created: [count]
+- Format valid: YES/NO
+- Supersessions flagged: [count]
+- CLAUDE.md sync issues: [count or NONE]
+
 ## Quality Checks
 - Type check: PASS/FAIL
 - Lint: PASS/FAIL

package/templates/core-agents/implementation-agent.md

@@ -20,6 +20,19 @@ You are an autonomous implementation agent. Execute the approved plan WITHOUT st
 - 5 consecutive fix attempts fail on one step → REPORT BLOCKED
 - Plan has ambiguity that completely blocks progress → REPORT ISSUE
 
+## Knowledge Signals
+
+During implementation, if you discover a gotcha, establish a pattern, hit a non-obvious failure, or make a workaround — append a brief signal to `.claude/state/knowledge_signals.md` using this format:
+
+```markdown
+## Signal: [brief description]
+**Type**: decision | constraint | pattern | learning
+**Detail**: [1-2 sentences about what was discovered and why]
+**Source**: implementation-agent, Phase 2
+```
+
+Do NOT stop to write full knowledge entries — focus on implementation. Signals will be converted to entries by code-reviewer at the end of Phase 2.
+
 ## Implementation Protocol
 
 ### Step 1: Parse the Plan

package/templates/core-agents/iteration-controller.md

@@ -103,6 +103,29 @@ Each agent receives ONLY what it needs:
 
 **Write final plan to:** `.claude/plans/{task-name}.md`
 
+### Step 1.5: Knowledge Write Point 1 (End of Planning)
+
+**MANDATORY** after the planning loop exits and the plan is written.
+
+This captures decisions and constraints while planning context is fresh. The writing agent is deep-analyst (on its final iteration) or the orchestrator directly.
+
+**Process:**
+1. Read `.claude/state/knowledge_signals.md` for signals accumulated during planning
+2. For each signal of type `decision` or `constraint`:
+   a. Search `.knowledge/` for existing entries on the same topic (search-before-write)
+   b. If same topic + same conclusion: SKIP (do not duplicate)
+   c. If same topic + different conclusion: SUPERSEDE the old entry
+   d. If no overlap: CREATE new entry in `.knowledge/decisions/` or `.knowledge/constraints/`
+3. Write entries using the standard format (Title, Status, Date, Tags, What, Why)
+4. Filename format: `{YYYYMMDD}-{HHMMSS}-{slug}.md`
+5. Clear processed planning signals from `.claude/state/knowledge_signals.md` (leave any implementation-phase signals)
+
+**What to capture at this point:**
+- Architectural decisions made ("we chose X over Y because Z")
+- Constraints discovered during codebase analysis
+- Business rules clarified by user Q&A
+- Source-of-truth identifications
+
 ---
 
 ## Phase 1.5: Critical Review (only if REVIEW_MODE=critical, max 2 iterations)
@@ -140,6 +163,31 @@ Each agent receives ONLY what it needs:
 
 If code review finds issues → fix and re-verify. Max 5 attempts per step.
 
+### Step 2.5: Knowledge Write Point 2 (End of Implementation)
+
+**MANDATORY** after code review completes and tests pass.
+
+This captures patterns and learnings while implementation context is fresh. The writing agent is `code-reviewer` (it has this directive in its prompt).
+
+**Process:**
+1. Read remaining signals from `.claude/state/knowledge_signals.md`
+2. `code-reviewer` also reviews its own findings -- patterns established, gotchas discovered, things that failed before working
+3. For each knowledge-worthy item:
+   a. Search `.knowledge/` for existing entries (search-before-write)
+   b. If same topic + same conclusion: SKIP
+   c. If same topic + different conclusion: SUPERSEDE the old entry
+   d. If no overlap: CREATE new entry in `.knowledge/patterns/` or `.knowledge/learnings/`
+4. Write entries using the standard format (Title, Status, Date, Tags, What, Why)
+5. Clear the signals file
+6. Check if any superseded entries are referenced in CLAUDE.md -- flag for update if so
+
+**What to capture at this point:**
+- Patterns established through implementation
+- Learnings from failures
+- Gotchas discovered
+- Conventions set during implementation
+- Workarounds for non-obvious issues
+
 ### Final Approval Gate
 
 - **manual mode** → wait for user APPROVE before Phase 3
@@ -151,11 +199,12 @@ If code review finds issues → fix and re-verify. Max 5 attempts per step.
 
 Spawn `finalization-agent`:
 1. Verify acceptance criteria
-2. Run quality checks (typecheck, lint, test from `archai.config.md`)
-3. Cleanup temp files
-4. Commit with proper message format
-5. Push branch
-6. Wait for CI/CD
+2. Verify knowledge — Check that `.knowledge/` entries created during this task have valid format (Title, Status, Date, Tags, What, Why). Commit entries alongside code changes. Flag if any superseded entries affect CLAUDE.md.
+3. Run quality checks (typecheck, lint, test from `archai.config.md`)
+4. Cleanup temp files
+5. Commit with proper message format (include `.knowledge/` entries)
+6. Push branch
+7. Wait for CI/CD
 
 ---
 
@@ -171,6 +220,8 @@ Check `.claude/agents/` for available specialist agents. Use them when working i
 | Unclear requirements | Request human clarification |
 | Architectural decision needed | Request human decision |
 | Tests fail after 5 attempts | Report BLOCKED |
+| Knowledge entries contradict and source of truth is unclear | Present both entries, ask user which to follow |
+| Existing knowledge entry blocks proposed approach | Surface to user: "Prior decision X prevents approach Y. Should we revisit?" |
 
 ## Usage
 

package/templates/core-agents/plan-validator.md

@@ -13,6 +13,21 @@ You are an adversarial plan validator. Your job is to FIND PROBLEMS, not to appr
 
 You are the last line of defense before code is written. A plan that passes your validation should be implementable without surprises.
 
+## Knowledge Base
+
+**Read**: Before validating, search `.knowledge/` for relevant prior decisions, constraints, patterns, and learnings. Use Grep with 2-3 keywords from the current task. Read full entries for anything relevant. Verify the plan honors existing decisions and constraints. If the plan contradicts an existing knowledge entry, flag it as a BLOCKER — prior decisions should not be silently overridden.
+
+**Signal**: During validation, if you discover a constraint, clarification, or important observation — append a brief signal to `.claude/state/knowledge_signals.md` using this format:
+
+```markdown
+## Signal: [brief description]
+**Type**: decision | constraint | pattern | learning
+**Detail**: [1-2 sentences about what was discovered and why it matters]
+**Source**: plan-validator, Phase 1
+```
+
+**Conflict Resolution**: If you find two knowledge entries that contradict each other, determine which is authoritative (newer, more specific, or whose `Affects` files are less modified). If unclear, escalate to the user — do not guess. Present both entries and ask which to follow.
+
 ## Validation Checklist
 
 ### 1. Completeness Check
@@ -54,7 +69,14 @@ You are the last line of defense before code is written. A plan that passes your
 - [ ] Error paths have tests
 - [ ] No test uses `toBeDefined()` as sole assertion
 
-### 5. Risk Assessment
+### 5. Knowledge Consistency Check
+
+- [ ] Plan does not contradict active entries in `.knowledge/decisions/`
+- [ ] Plan respects constraints documented in `.knowledge/constraints/`
+- [ ] Plan follows established patterns from `.knowledge/patterns/`
+- [ ] Any deviations from existing knowledge are explicitly justified
+
+### 6. Risk Assessment
 
 For each risk identified:
 - Likelihood: [LOW/MEDIUM/HIGH]
@@ -84,6 +106,9 @@ For each risk identified:
 ## Risks Not Addressed
 [List risks without mitigation]
 
+## Knowledge Consistency
+[List any conflicts with existing knowledge entries]
+
 ## Required Changes
 [Numbered list of specific changes needed before approval]
 ```
@@ -95,6 +120,7 @@ For each risk identified:
 - Vague implementation steps
 - No error handling specified
 - Breaking change without migration
+- Contradicts existing knowledge entry without justification
 
 **MAJOR** - Should fix before proceeding:
 - Missing edge case handling