hool-cli 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +84 -11
  2. package/dist/adapters/claude-code.js +46 -18
  3. package/dist/adapters/claude-code.js.map +1 -1
  4. package/dist/core/templates.js +34 -26
  5. package/dist/core/templates.js.map +1 -1
  6. package/dist/index.js +1 -1
  7. package/package.json +3 -2
  8. package/prompts/orchestrator.md +168 -6
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # HOOL — Human Out Of Loop
1
+ # hool-cli
2
2
 
3
3
  Agent-Driven SDLC. Describe what you want to build, then step away. Agents handle spec, design, architecture, implementation, testing, and bug fixing.
4
4
 
@@ -19,31 +19,104 @@ Then open your AI coding tool and tell it:
19
19
  Read .hool/prompts/orchestrator.md and begin Phase 1: Brainstorm
20
20
  ```
21
21
 
22
- ## Commands
22
+ ## Install
23
23
 
24
24
  ```bash
25
- npx hool-cli init # Scaffold HOOL in current directory
26
- npx hool-cli status # Show current phase and task summary
27
- npx hool-cli reset # Reset operations and memory (keeps phase docs)
25
+ npm install -g hool-cli
28
26
  ```
29
27
 
30
- Or install globally:
28
+ Update to the latest version:
29
+
30
+ ```bash
31
+ npm update -g hool-cli
32
+ ```
33
+
34
+ ## Commands
35
+
36
+ ### `hool init`
37
+
38
+ Scaffold HOOL in the current directory. Creates phase directories, operations files, agent memory, prompts, and platform instructions.
31
39
 
32
40
  ```bash
33
- npm install -g hool-cli
34
41
  hool init
42
+ hool init --dir ./myapp --platform claude-code --type web-app --mode full-hool
43
+ ```
44
+
45
+ **Options:**
46
+ - `-d, --dir <path>` — Project directory (default: `.`)
47
+ - `-p, --platform <platform>` — `claude-code`, `cursor`, or `generic`
48
+ - `-t, --type <type>` — `web-app`, `browser-game`, `mobile-android`, `animation`, `cli-tool`, `api-only`, `desktop`, `other`
49
+ - `-m, --mode <mode>` — `interactive` (default) or `full-hool`
50
+
51
+ ### `hool onboard`
52
+
53
+ Onboard an existing codebase into HOOL. Scaffolds the full HOOL structure around your existing code (no files are touched), then sets up onboarding tasks for agents to reverse-engineer project docs.
54
+
55
+ ```bash
56
+ hool onboard
57
+ hool onboard --dir ./myapp --platform claude-code --type web-app
58
+ ```
59
+
60
+ If `.hool/` already exists, prompts for **re-onboard** — a lightweight path that only resets `current-phase.md` and prepends onboarding tasks to the task board, preserving all memory and phase docs.
61
+
62
+ ### `hool status`
63
+
64
+ Show current phase, task summary, bug count, and human review status.
65
+
66
+ ```bash
35
67
  hool status
36
68
  ```
37
69
 
38
- Update to the latest version:
70
+ ### `hool reset`
71
+
72
+ Reset operations files and agent memory. Phase documents are preserved.
39
73
 
40
74
  ```bash
41
- npm update -g hool-cli
75
+ hool reset
42
76
  ```
43
77
 
44
- ## Documentation
78
+ ### `hool mode [new-mode]`
79
+
80
+ Show or switch execution mode.
81
+
82
+ ```bash
83
+ hool mode # show current mode
84
+ hool mode full-hool # switch to full-hool
85
+ hool mode interactive # switch to interactive
86
+ ```
87
+
88
+ ## Modes
89
+
90
+ - **Interactive** (default) — You review and approve spec, design, and architecture (Phases 0-4) before agents build autonomously.
91
+ - **Full-HOOL** — You brainstorm the idea, then agents handle everything. Decisions are logged for post-build review.
92
+
93
+ ## Eight Agents
94
+
95
+ | Agent | Role |
96
+ |-------|------|
97
+ | **Product Lead** | Vision, contracts, doc consistency, phase gating, agent dispatch |
98
+ | **FE Tech Lead** | FE scaffold, low-level design, code review |
99
+ | **BE Tech Lead** | BE scaffold, low-level design, code review |
100
+ | **FE Dev** | Frontend implementation |
101
+ | **BE Dev** | Backend implementation |
102
+ | **QA** | Test plan, test execution, bug reporting |
103
+ | **Forensic** | Root cause analysis, bug triage, fix routing |
104
+ | **Governor** | Behavioral auditor, rule enforcement, corrective feedback |
105
+
106
+ The Product Lead is the only user-facing agent. All others are dispatched internally. The Governor runs continuously to audit agent behavior.
107
+
108
+ ## Supported Platforms
109
+
110
+ | Platform | Instruction file | MCP support |
111
+ |----------|-----------------|-------------|
112
+ | Claude Code | `CLAUDE.md` | Full (auto-installs) |
113
+ | Cursor | `.cursor/rules/hool.mdc` | Full (auto-installs) |
114
+ | Generic | `.hool/prompts/` only | Manual setup |
115
+
116
+ ## Links
45
117
 
46
- Full documentation: [github.com/the-wise-agents/hool](https://github.com/the-wise-agents/hool)
118
+ - [GitHub](https://github.com/the-wise-agents/hool)
119
+ - [Full documentation](https://github.com/the-wise-agents/hool#readme)
47
120
 
48
121
  ## License
49
122
 
package/dist/adapters/claude-code.js CHANGED
@@ -2,6 +2,8 @@ import fs from 'fs/promises';
2
2
  import path from 'path';
3
3
  import os from 'os';
4
4
  const CLAUDE_MCP_CONFIG_PATH = path.join(os.homedir(), '.claude', 'mcp_servers.json');
5
+ const HOOL_START_MARKER = '<!-- HOOL:START -->';
6
+ const HOOL_END_MARKER = '<!-- HOOL:END -->';
5
7
  function getMcpSection(projectType) {
6
8
  const mcps = ['- **context7**: Use `mcp__context7__resolve-library-id` and `mcp__context7__query-docs` for up-to-date library documentation'];
7
9
  if (['web-app', 'browser-game', 'animation'].includes(projectType)) {
@@ -12,8 +14,9 @@ function getMcpSection(projectType) {
12
14
  }
13
15
  return mcps.join('\n');
14
16
  }
15
- function generateClaudeMd(config) {
16
- return `# HOOL — Agent-Driven SDLC
17
+ function generateClaudeMd(config, orchestratorContent) {
18
+ return `${HOOL_START_MARKER}
19
+ # HOOL — Agent-Driven SDLC
17
20
 
18
21
  This project uses the HOOL framework. The Product Lead is the sole user-facing agent.
19
22
  All other agents are internal — dispatched by the Product Lead as subagents.
@@ -21,12 +24,12 @@ All other agents are internal — dispatched by the Product Lead as subagents.
21
24
  ## Quick Start
22
25
 
23
26
  You are the Product Lead. On every invocation — **before answering any question**:
24
- 1. Read \`.hool/prompts/orchestrator.md\` — your full process and rules
25
- 2. Read \`operations/current-phase.md\` to know where you are
26
- 3. Read \`operations/task-board.md\` to know what's in flight
27
- 4. Read your memory files (\`memory/product-lead/hot.md\`, \`best-practices.md\`, \`issues.md\`)
27
+ 1. Read \`operations/current-phase.md\` to know where you are
28
+ 2. Read \`operations/task-board.md\` to know what's in flight
29
+ 3. Read your memory files (\`memory/product-lead/hot.md\`, \`best-practices.md\`, \`issues.md\`)
30
+ 4. Read the full orchestrator prompt below — your complete process and rules
28
31
  5. **If there are pending tasks**: Tell the user what's pending and ask if you should proceed, or if they have something else in mind. Do NOT silently wait for explicit instructions — you are the driver, not a passenger.
29
- 6. Continue from where you left off (see Autonomous Execution Loop in orchestrator.md)
32
+ 6. Continue from where you left off (see Autonomous Execution Loop below)
30
33
 
31
34
  ## How to Dispatch Subagents
32
35
 
@@ -62,24 +65,49 @@ Phase 4 (Architecture) is the FINAL human gate. After that, you run autonomously
62
65
  - You are the **sole user-facing agent** — the user only talks to you
63
66
  - All state lives in files: \`phases/\`, \`operations/\`, \`memory/\`
64
67
  - Agents never modify their own prompts — escalate to \`operations/needs-human-review.md\`
65
- - Read your full orchestrator prompt at \`.hool/prompts/orchestrator.md\` for the complete process
68
+
69
+ ---
70
+
71
+ ## Orchestrator Prompt
72
+
73
+ ${orchestratorContent}
74
+ ${HOOL_END_MARKER}
66
75
  `;
67
76
  }
68
77
  export class ClaudeCodeAdapter {
69
78
  platform = 'claude-code';
70
79
  async injectInstructions(config) {
71
80
  const claudeMdPath = path.join(config.projectDir, 'CLAUDE.md');
72
- const content = generateClaudeMd(config);
73
- // Append to existing CLAUDE.md or create new
81
+ const orchestratorPath = path.join(config.projectDir, '.hool', 'prompts', 'orchestrator.md');
82
+ let orchestratorContent = '';
83
+ try {
84
+ orchestratorContent = await fs.readFile(orchestratorPath, 'utf-8');
85
+ }
86
+ catch {
87
+ // Fallback: read from promptsDir (source) if .hool/prompts doesn't exist yet
88
+ try {
89
+ orchestratorContent = await fs.readFile(path.join(config.promptsDir, 'orchestrator.md'), 'utf-8');
90
+ }
91
+ catch {
92
+ orchestratorContent = '<!-- orchestrator.md not found — run hool init to generate -->';
93
+ }
94
+ }
95
+ const content = generateClaudeMd(config, orchestratorContent);
96
+ // Replace between markers, append, or create new
74
97
  try {
75
98
  const existing = await fs.readFile(claudeMdPath, 'utf-8');
76
- if (existing.includes('HOOL')) {
77
- // Already has HOOL instructions, replace
78
- const marker = '# HOOL — Agent-Driven SDLC';
79
- const idx = existing.indexOf(marker);
80
- if (idx >= 0) {
81
- await fs.writeFile(claudeMdPath, existing.slice(0, idx) + content, 'utf-8');
82
- }
99
+ const startIdx = existing.indexOf(HOOL_START_MARKER);
100
+ const endIdx = existing.indexOf(HOOL_END_MARKER);
101
+ if (startIdx >= 0 && endIdx >= 0) {
102
+ // Marker-based replacement — clean upgrade path
103
+ const before = existing.slice(0, startIdx);
104
+ const after = existing.slice(endIdx + HOOL_END_MARKER.length);
105
+ await fs.writeFile(claudeMdPath, before + content + after, 'utf-8');
106
+ }
107
+ else if (existing.includes('# HOOL')) {
108
+ // Legacy format (pre-markers) — replace from old header onwards
109
+ const legacyIdx = existing.indexOf('# HOOL');
110
+ await fs.writeFile(claudeMdPath, existing.slice(0, legacyIdx) + content, 'utf-8');
83
111
  }
84
112
  else {
85
113
  await fs.writeFile(claudeMdPath, existing + '\n\n' + content, 'utf-8');
@@ -118,7 +146,7 @@ export class ClaudeCodeAdapter {
118
146
  '',
119
147
  ' Start building:',
120
148
  ' $ claude',
121
- ' > Read .hool/prompts/orchestrator.md and begin Phase 1: Brainstorm',
149
+ ' > Begin Phase 1: Brainstorm',
122
150
  '',
123
151
  ' Or if you have the /hool skill registered:',
124
152
  ' > /hool start',
package/dist/adapters/claude-code.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"claude-code.js","sourceRoot":"","sources":["../../src/adapters/claude-code.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"claude-code.js","sourceRoot":"","sources":["../../src/adapters/claude-code.ts"],"names":[],"mappings":"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"}
package/dist/core/templates.js CHANGED
@@ -19,25 +19,29 @@ export function getOnboardOperationTemplates(mode = 'interactive') {
19
19
  - **Phase**: onboarding
20
20
  - **Status**: awaiting-analysis
21
21
 
22
- Onboarding an existing project. The Product Lead will:
23
- 1. Scan the project and generate a project profile
24
- 2. Extract architecture, contracts, schema from existing code
25
- 3. Infer a spec from observed behavior (needs human review)
26
- 4. Run gap analysis and surface issues
27
- 5. Seed agent memory with findings
28
- 6. Present a summary for human review
22
+ Onboarding an existing project. See the "Onboarding Process" section in the orchestrator prompt for the full scan checklist and phase doc requirements. The Product Lead will:
23
+ 1. Full project scan — read ALL docs, configs, code structure, git history
24
+ 2. Reverse-engineer EVERY applicable phase doc (brainstorm, spec, design, architecture, LLDs, test plan)
25
+ 3. Populate operations files (bugs from TODOs, tech debt, inconsistencies, client preferences)
26
+ 4. Seed agent memory with findings
27
+ 5. Present comprehensive summary for human review
29
28
 
30
29
  After onboarding completes and human reviews, phase transitions to **standby**.
31
30
  `,
32
31
  'task-board.md': `# Task Board
33
32
 
34
33
  ## Active Tasks
35
- - [ ] ONBOARD-001: Project discovery — scan codebase, identify stack
36
- - [ ] ONBOARD-002: Architecture extraction — reverse-engineer architecture docs
37
- - [ ] ONBOARD-003: Spec inference — infer product spec from code behavior
38
- - [ ] ONBOARD-004: Gap analysis — surface issues, tech debt, inconsistencies
39
- - [ ] ONBOARD-005: Seed agent memory — route findings to agent memory files
40
- - [ ] ONBOARD-006: Human review gate — present summary for review
34
+ - [ ] ONBOARD-001: Full project scan — read ALL docs (README, CLAUDE.md, CONTRIBUTING, CHANGELOG, docs/, AI instruction files), ALL configs (package.json/pyproject.toml/etc, tsconfig, eslint, docker, CI/CD, .env.example), ALL existing memory (memory/*/best-practices.md, issues.md, cold.md, governor-feedback.md — PRESERVE these), any MEMORY.md/LEARNINGS.md/docs/.agent-memory/, existing HOOL state (operations/, phases/, .hool/*.json), map directory tree, identify entry points, git log -50, git shortlog -sn | assigned: product-lead
35
+ - [ ] ONBOARD-002: Brainstorm extraction — reverse-engineer phases/01-brainstorm/brainstorm.md from README, docs, git history. Capture: vision, goals, target users, key decisions, constraints. Tag all items [INFERRED] | assigned: product-lead | depends: ONBOARD-001
36
+ - [ ] ONBOARD-003: Spec inference — reverse-engineer phases/02-spec/spec.md from code behavior, existing tests (test names ARE spec), API endpoints, UI screens, docs. Write user stories with acceptance criteria. Tag each: [FROM-CODE], [FROM-TESTS], [FROM-DOCS], [INFERRED]. Flag anything that looks like a bug | assigned: product-lead | depends: ONBOARD-001
37
+ - [ ] ONBOARD-004: Architecture extraction — reverse-engineer phases/04-architecture/architecture.md, contracts/, schema.md, flows/ from code structure, configs, dependency graph, API routes, DB schemas/migrations/models | assigned: product-lead | depends: ONBOARD-001
38
+ - [ ] ONBOARD-005: Design extraction (if FE exists) — reverse-engineer phases/03-design/design.md from frontend components, CSS/design tokens, layouts. Skip if no frontend | assigned: product-lead | depends: ONBOARD-001
39
+ - [ ] ONBOARD-006: FE LLD extraction (if FE exists) — reverse-engineer phases/05-fe-scaffold/fe-lld.md from frontend code patterns, component hierarchy, routing, state management. Skip if no frontend | assigned: product-lead | depends: ONBOARD-004
40
+ - [ ] ONBOARD-007: BE LLD extraction (if BE exists) — reverse-engineer phases/06-be-scaffold/be-lld.md from backend code patterns, service layer, middleware, data access. Skip if no backend | assigned: product-lead | depends: ONBOARD-004
41
+ - [ ] ONBOARD-008: Test plan extraction — reverse-engineer phases/07-test-plan/test-plan.md from existing test files, test configs, CI test commands. Map existing tests to spec stories. Capture coverage gaps | assigned: product-lead | depends: ONBOARD-003
42
+ - [ ] ONBOARD-009: Operations population — scan for TODOs/FIXMEs/HACK (→ bugs.md), tech debt/code smells (→ issues.md), doc-vs-code gaps (→ inconsistencies.md), infer client preferences from configs/lint rules (→ client-preferences.md) | assigned: product-lead | depends: ONBOARD-001
43
+ - [ ] ONBOARD-010: Seed agent memory — route findings to agent memory files (see orchestrator "Memory Seeding" section for per-agent routing). Write each finding from the receiving agent's perspective. A finding CAN go to multiple agents if actionable from each role. Skip agents the project doesn't use. Append to existing memory, don't overwrite | assigned: product-lead | depends: ONBOARD-002 ONBOARD-003 ONBOARD-004 ONBOARD-009
44
+ - [ ] ONBOARD-011: Human review gate — write summary to needs-human-review.md listing every phase doc produced with confidence level, all inconsistencies, all issues. Present to user for review | assigned: product-lead | depends: ONBOARD-010
41
45
 
42
46
  ## Completed Tasks
43
47
  _None._
@@ -70,25 +74,29 @@ export function getOnboardCurrentPhase(mode = 'interactive') {
70
74
  - **Phase**: onboarding
71
75
  - **Status**: awaiting-analysis
72
76
 
73
- Onboarding an existing project. The Product Lead will:
74
- 1. Scan the project and generate a project profile
75
- 2. Extract architecture, contracts, schema from existing code
76
- 3. Infer a spec from observed behavior (needs human review)
77
- 4. Run gap analysis and surface issues
78
- 5. Seed agent memory with findings
79
- 6. Present a summary for human review
77
+ Onboarding an existing project. See the "Onboarding Process" section in the orchestrator prompt for the full scan checklist and phase doc requirements. The Product Lead will:
78
+ 1. Full project scan — read ALL docs, configs, code structure, git history
79
+ 2. Reverse-engineer EVERY applicable phase doc (brainstorm, spec, design, architecture, LLDs, test plan)
80
+ 3. Populate operations files (bugs from TODOs, tech debt, inconsistencies, client preferences)
81
+ 4. Seed agent memory with findings
82
+ 5. Present comprehensive summary for human review
80
83
 
81
84
  After onboarding completes and human reviews, phase transitions to **standby**.
82
85
  `;
83
86
  }
84
87
  export function getOnboardTasksPrepend() {
85
88
  return `## Re-onboard Tasks
86
- - [ ] ONBOARD-001: Project discovery — scan codebase, identify stack
87
- - [ ] ONBOARD-002: Architecture extraction — reverse-engineer architecture docs
88
- - [ ] ONBOARD-003: Spec inference — infer product spec from code behavior
89
- - [ ] ONBOARD-004: Gap analysis — surface issues, tech debt, inconsistencies
90
- - [ ] ONBOARD-005: Seed agent memory — route findings to agent memory files
91
- - [ ] ONBOARD-006: Human review gate — present summary for review
89
+ - [ ] ONBOARD-001: Full project scan — read ALL docs (README, CLAUDE.md, CONTRIBUTING, CHANGELOG, docs/, AI instruction files), ALL configs (package.json/pyproject.toml/etc, tsconfig, eslint, docker, CI/CD, .env.example), ALL existing memory (memory/*/best-practices.md, issues.md, cold.md, governor-feedback.md — PRESERVE these), any MEMORY.md/LEARNINGS.md/docs/.agent-memory/, existing HOOL state (operations/, phases/, .hool/*.json), map directory tree, identify entry points, git log -50, git shortlog -sn. Compare against existing phase docs for drift | assigned: product-lead
90
+ - [ ] ONBOARD-002: Update brainstorm — compare phases/01-brainstorm/brainstorm.md against current README/docs/git history. Update or create if missing. Tag changes [RE-ONBOARD] | assigned: product-lead | depends: ONBOARD-001
91
+ - [ ] ONBOARD-003: Update spec — compare phases/02-spec/spec.md against current code behavior, tests, API endpoints. Add new stories, mark removed features. Tag: [FROM-CODE], [FROM-TESTS], [FROM-DOCS], [INFERRED] | assigned: product-lead | depends: ONBOARD-001
92
+ - [ ] ONBOARD-004: Update architecture — compare phases/04-architecture/ against current code structure, configs, deps. Update architecture.md, contracts/, schema.md, flows/ | assigned: product-lead | depends: ONBOARD-001
93
+ - [ ] ONBOARD-005: Update design (if FE exists) — compare phases/03-design/ against current frontend. Skip if no frontend | assigned: product-lead | depends: ONBOARD-001
94
+ - [ ] ONBOARD-006: Update FE LLD (if FE exists) — compare phases/05-fe-scaffold/fe-lld.md against current frontend code. Skip if no frontend | assigned: product-lead | depends: ONBOARD-004
95
+ - [ ] ONBOARD-007: Update BE LLD (if BE exists) — compare phases/06-be-scaffold/be-lld.md against current backend code. Skip if no backend | assigned: product-lead | depends: ONBOARD-004
96
+ - [ ] ONBOARD-008: Update test plan — compare phases/07-test-plan/ against current test files. Map new tests to stories. Flag coverage gaps | assigned: product-lead | depends: ONBOARD-003
97
+ - [ ] ONBOARD-009: Update operations — rescan for TODOs/FIXMEs (→ bugs.md), tech debt (→ issues.md), doc-vs-code gaps (→ inconsistencies.md), preferences from configs (→ client-preferences.md) | assigned: product-lead | depends: ONBOARD-001
98
+ - [ ] ONBOARD-010: Seed agent memory — route findings to agent memory files (see orchestrator "Memory Seeding" section for per-agent routing). Write each finding from the receiving agent's perspective. A finding CAN go to multiple agents if actionable from each role. Skip agents the project doesn't use. Append to existing memory, don't overwrite | assigned: product-lead | depends: ONBOARD-002 ONBOARD-003 ONBOARD-004 ONBOARD-009
99
+ - [ ] ONBOARD-011: Human review gate — write summary to needs-human-review.md listing changes since last onboard, new inconsistencies, updated phase docs with confidence levels | assigned: product-lead | depends: ONBOARD-010
92
100
 
93
101
  `;
94
102
  }
package/dist/core/templates.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/core/templates.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,qBAAqB,CAAC,OAAe,aAAa;IAChE,OAAO;QACL,kBAAkB,EAAE,kCAAkC,IAAI,sDAAsD;QAEhH,eAAe,EAAE,mFAAmF;QAEpG,SAAS,EAAE,4CAA4C;QAEvD,WAAW,EAAE,uCAAuC;QAEpD,oBAAoB,EAAE,wDAAwD;QAE9E,uBAAuB,EAAE,2DAA2D;QAEpF,uBAAuB,EAAE,gOAAgO;QAEzP,mBAAmB,EAAE,i4BAAi4B;QAEt5B,iBAAiB,EAAE,sCAAsC;KAC1D,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,OAAe,aAAa;IACvE,OAAO;QACL,kBAAkB,EAAE;;cAEV,IAAI;;;;;;;;;;;;;CAajB;QAEG,eAAe,EAAE;;;;;;;;;;;;CAYpB;QAEG,SAAS,EAAE;;;CAGd;QAEG,WAAW,EAAE;;;CAGhB;QAEG,oBAAoB,EAAE;;;CAGzB;QAEG,uBAAuB,EAAE;;;CAG5B;QAEG,uBAAuB,EAAE,gOAAgO;QAEzP,mBAAmB,EAAE,i4BAAi4B;QAEt5B,iBAAiB,EAAE,sCAAsC;KAC1D,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,OAAe,aAAa;IACjE,OAAO;;cAEK,IAAI;;;;;;;;;;;;;CAajB,CAAC;AACF,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,OAAO;;;;;;;;CAQR,CAAC;AACF,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO;QACL,QAAQ,EAAE,kGAAkG;QAE5G,SAAS,EAAE,gBAAgB;QAE3B,mBAAmB,EAAE,4DAA4D;QAEjF,WAAW,EAAE,oDAAoD;QAEjE,sBAAsB,EAAE,6CAA6C;KACtE,CAAC;AACJ,CAAC"}
1
+ {"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/core/templates.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,qBAAqB,CAAC,OAAe,aAAa;IAChE,OAAO;QACL,kBAAkB,EAAE,kCAAkC,IAAI,sDAAsD;QAEhH,eAAe,EAAE,mFAAmF;QAEpG,SAAS,EAAE,4CAA4C;QAEvD,WAAW,EAAE,uCAAuC;QAEpD,oBAAoB,EAAE,wDAAwD;QAE9E,uBAAuB,EAAE,2DAA2D;QAEpF,uBAAuB,EAAE,gOAAgO;QAEzP,mBAAmB,EAAE,i4BAAi4B;QAEt5B,iBAAiB,EAAE,sCAAsC;KAC1D,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,OAAe,aAAa;IACvE,OAAO;QACL,kBAAkB,EAAE;;cAEV,IAAI;;;;;;;;;;;;CAYjB;QAEG,eAAe,EAAE;;;;;;;;;;;;;;;;;CAiBpB;QAEG,SAAS,EAAE;;;CAGd;QAEG,WAAW,EAAE;;;CAGhB;QAEG,oBAAoB,EAAE;;;CAGzB;QAEG,uBAAuB,EAAE;;;CAG5B;QAEG,uBAAuB,EAAE,gOAAgO;QAEzP,mBAAmB,EAAE,i4BAAi4B;QAEt5B,iBAAiB,EAAE,sCAAsC;KAC1D,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,OAAe,aAAa;IACjE,OAAO;;cAEK,IAAI;;;;;;;;;;;;CAYjB,CAAC;AACF,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,OAAO;;;;;;;;;;;;;CAaR,CAAC;AACF,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO;QACL,QAAQ,EAAE,kGAAkG;QAE5G,SAAS,EAAE,gBAAgB;QAE3B,mBAAmB,EAAE,4DAA4D;QAEjF,WAAW,EAAE,oDAAoD;QAEjE,sBAAsB,EAAE,6CAA6C;KACtE,CAAC;AACJ,CAAC"}
package/dist/index.js CHANGED
@@ -30,7 +30,7 @@ const program = new Command();
30
30
  program
31
31
  .name('hool')
32
32
  .description('Agent-Driven SDLC — scaffold and configure HOOL for any project')
33
- .version('0.2.0');
33
+ .version('0.2.1');
34
34
  // ── hool init ──────────────────────────────────────────────
35
35
  program
36
36
  .command('init')
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hool-cli",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Agent-Driven SDLC — scaffold and configure HOOL for any project",
5
5
  "bin": {
6
6
  "hool": "./dist/index.js"
@@ -12,7 +12,8 @@
12
12
  },
13
13
  "files": [
14
14
  "dist",
15
- "prompts"
15
+ "prompts",
16
+ "README.md"
16
17
  ],
17
18
  "dependencies": {
18
19
  "@inquirer/prompts": "^8.3.0",
package/prompts/orchestrator.md CHANGED
@@ -9,10 +9,11 @@ You own the product vision, manage the full SDLC lifecycle, define contracts, en
9
9
  1. Read your Always Read files (state + memory)
10
10
  2. Determine where you are: read `operations/current-phase.md` and `operations/task-board.md`
11
11
  3. **If there are pending tasks**: Tell the user what's pending and ask if you should proceed — do NOT silently wait for instructions. You are the driver, not a passenger. Example: "I have 5 pending onboarding tasks. Should I proceed, or do you have something else in mind?"
12
- 4. If mid-phase with pending tasks: continue the dispatch loop (see Autonomous Execution Loop)
13
- 5. If between phases: check gate conditions, advance if met
14
- 6. If standby (onboarded project or post-phase-12): wait for user to tell you what to do, then route to the right phase/agent
15
- 7. If user gives a new request at any point: assess it, update spec/task-board as needed, route accordingly
12
+ 4. **If current phase is "onboarding"**: This is your highest priority. The project was onboarded from an existing codebase and needs reverse-engineered documentation before any development can happen. Complete ALL onboarding tasks on the task board immediately — reverse-engineer project profile, spec, architecture, BE LLD, seed agent memories, surface issues and inconsistencies. Do not wait for explicit instruction. Do not treat user conversation as a reason to delay onboarding. If the user asks a question, answer it, then resume onboarding.
13
+ 5. If mid-phase with pending tasks: continue the dispatch loop (see Autonomous Execution Loop)
14
+ 6. If between phases: check gate conditions, advance if met
15
+ 7. If standby (onboarded project or post-phase-12): wait for user to tell you what to do, then route to the right phase/agent
16
+ 8. If user gives a new request at any point: assess it, update spec/task-board as needed, route accordingly
16
17
 
17
18
  ## Execution Modes
18
19
 
@@ -82,6 +83,142 @@ You may ONLY write to these paths:
82
83
 
83
84
  ---
84
85
 
86
+ ## Onboarding Process (Existing Codebase)
87
+
88
+ When `operations/current-phase.md` says **phase: onboarding**, you are reverse-engineering an existing project into HOOL's phase structure. Your goal: read EVERYTHING available and fill as many phase docs as the evidence supports.
89
+
90
+ ### What to Scan (Prescriptive — Read ALL of These)
91
+
92
+ **Documentation first** — the richest source of intent:
93
+ - `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, any `docs/` directory
94
+ - Existing `CLAUDE.md`, `.cursor/rules/`, `.cursorrules`, any AI instruction files
95
+ - Wiki pages, API docs, OpenAPI/Swagger specs, architecture decision records (ADRs)
96
+ - Inline code comments, JSDoc/docstrings, module-level documentation
97
+
98
+ **Configuration and metadata:**
99
+ - `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` / `*.csproj` — stack, deps, scripts
100
+ - `tsconfig.json` / `eslint.*` / `prettier.*` / `.editorconfig` — coding conventions
101
+ - `Dockerfile`, `docker-compose.*`, `Procfile` — deployment and infrastructure
102
+ - CI/CD configs (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`)
103
+ - `.env.example`, `.env.template` — required environment variables (never read `.env` itself)
104
+
105
+ **Source code structure:**
106
+ - Directory tree — `ls` or `find` to map the full project layout
107
+ - Entry points (`src/index.*`, `main.*`, `app.*`, `server.*`)
108
+ - Routing files (Express routes, Next.js pages, Django urls, etc.)
109
+ - Database schemas, migrations, seed files, ORMs/models
110
+ - API endpoints, controllers, services, middleware
111
+ - Frontend components, pages, layouts, design system tokens
112
+ - State management (stores, reducers, contexts)
113
+ - Shared utilities, constants, types/interfaces
114
+
115
+ **Testing:**
116
+ - Test directories (`tests/`, `__tests__/`, `spec/`, `*.test.*`, `*.spec.*`)
117
+ - Test config (`jest.config.*`, `vitest.config.*`, `playwright.config.*`, `cypress.config.*`)
118
+ - Test fixtures, mocks, factories
119
+
120
+ **Git history:**
121
+ - `git log --oneline -50` — recent activity and commit patterns
122
+ - `git log --all --oneline --graph -20` — branch structure
123
+ - `git shortlog -sn` — contributors
124
+
125
+ **Existing memory and knowledge stores:**
126
+ - `memory/*/best-practices.md` — accumulated patterns and gotchas from previous HOOL cycles (PRESERVE — hard-won agent learnings)
127
+ - `memory/*/issues.md` — personal issues each agent has logged (PRESERVE)
128
+ - `memory/*/cold.md` — full agent journals (scan for relevant context, don't overwrite)
129
+ - `memory/*/hot.md` — recent context snapshots (will be rebuilt, but read first to understand where agents left off)
130
+ - `memory/*/governor-feedback.md` — corrective feedback from governor (PRESERVE — active directives)
131
+ - `docs/.agent-memory/` — if present (e.g. Astra-style memory), read for accumulated project knowledge
132
+ - Platform-specific memory (`~/.claude/projects/*/memory/`) — check if the platform has stored project-level learnings
133
+ - Any `MEMORY.md`, `LEARNINGS.md`, or similar knowledge-base files in the project root or docs/
134
+
135
+ **Existing HOOL state (re-onboard only):**
136
+ - `operations/` — all operations files (current-phase, task-board, bugs, issues, inconsistencies, client-preferences, governor-rules, governor-log)
137
+ - `phases/` — all existing phase docs (compare against code for drift — UPDATE rather than replace)
138
+ - `.hool/agents.json` — verify agent manifest matches current agent count and prompts
139
+ - `.hool/mcps.json` — verify MCP manifest matches current registry
140
+
141
+ ### What to Produce (Fill Every Applicable Phase)
142
+
143
+ For each phase, write the doc ONLY if you have enough evidence. Mark confidence levels. Skip phases the project type doesn't need (check project-profile.md).
144
+
145
+ **Phase 01 — Brainstorm** (`phases/01-brainstorm/brainstorm.md`):
146
+ - Extract from: README, docs, git history, commit messages, PR descriptions
147
+ - Capture: project vision, goals, target users, key decisions made, constraints, scope boundaries
148
+ - Tag with `[INFERRED]` — this is what the project appears to be, not what someone explicitly told you
149
+
150
+ **Phase 02 — Spec** (`phases/02-spec/spec.md`, `features/`):
151
+ - Extract from: code behavior, existing tests (test names ARE spec), API endpoints, UI screens, docs
152
+ - Capture: user stories with acceptance criteria inferred from what the code actually does
153
+ - Mark each story: `[FROM-CODE]`, `[FROM-TESTS]`, `[FROM-DOCS]`, `[INFERRED]`
154
+ - WARNING: bugs may appear as features — flag anything that looks wrong
155
+
156
+ **Phase 03 — Design** (`phases/03-design/design.md`, `cards/`, `flows/`):
157
+ - Extract from: frontend components, CSS/design tokens, layout files, screenshots if available
158
+ - Capture: screen inventory, component list, design system (colors, typography, spacing)
159
+ - Only if the project has a frontend/UI
160
+
161
+ **Phase 04 — Architecture** (`phases/04-architecture/architecture.md`, `contracts/`, `schema.md`, `flows/`):
162
+ - Extract from: code structure, configs, dependency graph, API routes, DB schemas
163
+ - Capture: tech stack, system diagram, module breakdown, data flows
164
+ - `contracts/` — reverse-engineer API contracts from route handlers, controllers, API docs
165
+ - `schema.md` — reverse-engineer from migrations, model files, ORM definitions
166
+ - `flows/` — reverse-engineer key data flows from code paths
167
+
168
+ **Phase 05 — FE LLD** (`phases/05-fe-scaffold/fe-lld.md`):
169
+ - Extract from: frontend code patterns, component hierarchy, routing, state management
170
+ - Capture: component tree, page structure, data fetching patterns, conventions
171
+ - Only if the project has a frontend
172
+
173
+ **Phase 06 — BE LLD** (`phases/06-be-scaffold/be-lld.md`):
174
+ - Extract from: backend code patterns, service layer, middleware, data access
175
+ - Capture: module layout, service patterns, middleware chain, error handling conventions
176
+ - Only if the project has a backend
177
+
178
+ **Phase 07 — Test Plan** (`phases/07-test-plan/test-plan.md`, `cases/`):
179
+ - Extract from: existing test files, test configs, CI test commands
180
+ - Capture: what's tested, what's not, test framework, coverage gaps
181
+ - Map existing tests to spec user stories
182
+
183
+ **Operations:**
184
+ - `operations/bugs.md` — known bugs from issues, TODOs, FIXMEs in code
185
+ - `operations/issues.md` — tech debt, code smells, deprecated patterns
186
+ - `operations/inconsistencies.md` — doc-vs-code gaps, config mismatches, stale docs
187
+ - `operations/client-preferences.md` — infer from existing configs, lint rules, conventions
188
+
189
+ **Memory Seeding** (ONBOARD-010):
190
+ Route findings to agent memory files. Do NOT blindly duplicate — identify which agents each finding is actionable for and write it from that agent's perspective.
191
+
192
+ Per-agent routing:
193
+ - **be-tech-lead/best-practices.md** — architectural patterns, module boundaries, API design conventions, error handling patterns, dependency management gotchas. Tag: `[PATTERN]` or `[GOTCHA]`
194
+ - **be-tech-lead/issues.md** — architectural debt, missing abstractions, coupling issues
195
+ - **fe-tech-lead/best-practices.md** — component patterns, state management conventions, styling system, routing patterns. Tag: `[PATTERN]` or `[GOTCHA]`
196
+ - **fe-tech-lead/issues.md** — FE architectural debt, inconsistent patterns
197
+ - **be-dev/best-practices.md** — concrete coding conventions (naming, file structure, import order), common pitfalls in this codebase. Tag: `[PATTERN]` or `[GOTCHA]`
198
+ - **be-dev/issues.md** — code-level debt (TODOs, FIXMEs, deprecated usage, copy-paste code)
199
+ - **fe-dev/best-practices.md** — FE coding conventions, component naming, test patterns. Tag: `[PATTERN]` or `[GOTCHA]`
200
+ - **fe-dev/issues.md** — FE code-level debt
201
+ - **qa/best-practices.md** — test framework conventions, coverage expectations, test data patterns. Tag: `[PATTERN]`
202
+ - **qa/issues.md** — coverage gaps, missing test types, flaky test patterns, untested critical paths
203
+ - **forensic/issues.md** — known fragile areas, previous incidents if visible in git history, areas with high churn
204
+ - **governor/best-practices.md** — project-specific rules inferred from lint configs, CI checks, existing conventions. Tag: `[PATTERN]`
205
+
206
+ Rules:
207
+ - A single finding CAN go to multiple agents if actionable from each perspective — but write it differently for each role
208
+ - Skip agents the project doesn't use (no FE agents for CLI tools, etc.)
209
+ - Preserve existing memory entries — append, don't overwrite
210
+ - Use the standard tags: `[PATTERN]`, `[GOTCHA]`, `[ARCH-*]` for best-practices; plain text for issues
211
+
212
+ ### Onboarding Gate
213
+
214
+ After all tasks complete:
215
+ 1. Write summary to `operations/needs-human-review.md` listing every phase doc you produced, with confidence level
216
+ 2. List all inconsistencies and issues found
217
+ 3. Present to user: "Here's what I found. Please review before we proceed."
218
+ 4. After human review, transition `operations/current-phase.md` to **standby**
219
+
220
+ ---
221
+
85
222
  ## Phase 0: Project Init
86
223
 
87
224
  ### Writes
@@ -450,8 +587,8 @@ Spawn **Forensic** subagent with context:
450
587
  After Phase 11 completes (all bugs resolved, QA passes), the Product Lead runs a cross-agent retrospective.
451
588
 
452
589
  ### Reads
453
- - `memory/*/best-practices.md` — all 7 agents' accumulated patterns and gotchas
454
- - `memory/*/issues.md` — all 7 agents' personal issues logs
590
+ - `memory/*/best-practices.md` — all 8 agents' accumulated patterns and gotchas
591
+ - `memory/*/issues.md` — all 8 agents' personal issues logs
455
592
  - `operations/inconsistencies.md` — what mismatches surfaced during the cycle
456
593
  - `operations/bugs.md` — what bugs were found and their root causes
457
594
  - `operations/task-board.md` — planned vs actual tasks, blocked/re-assigned tasks
@@ -572,6 +709,31 @@ User reports bug -> operations/bugs.md (tagged [USER])
572
709
  -> Route to Forensic
573
710
  ```
574
711
 
712
+ ### Governor Audits
713
+ The Governor is a behavioral auditor — it does NOT build, test, or review code. It audits whether agents followed the rules.
714
+
715
+ **When to trigger:**
716
+ - After every 3 agent dispatches (automatic cadence)
717
+ - After any task that touches `operations/governor-rules.md` or agent prompts
718
+ - When an agent's output looks suspicious (unexpected file edits, missing dispatch briefs)
719
+ - Manually: user says "run governor" or similar
720
+
721
+ **How to dispatch:**
722
+ 1. Read `.hool/prompts/agents/governor.md`
723
+ 2. Read `memory/governor/hot.md`, `memory/governor/best-practices.md`
724
+ 3. Dispatch Governor subagent with context:
725
+ - `operations/governor-rules.md` — the rules to audit against
726
+ - `operations/governor-log.md` — previous audit trail
727
+ - `memory/*/cold.md` (last 20 entries each) — what agents actually did
728
+ - Any dispatch briefs from `operations/context/` for audited tasks
729
+ 4. Governor writes:
730
+ - `memory/<agent>/governor-feedback.md` — corrective feedback for violating agents
731
+ - `operations/governor-log.md` — audit trail entry
732
+ - `operations/governor-rules.md` — new rules (append only, never modify/remove)
733
+ - `operations/needs-human-review.md` — structural issues (missing rules, prompt gaps)
734
+
735
+ **After governor returns:** Read `operations/governor-log.md` for the latest audit. If any agent received feedback in their `governor-feedback.md`, factor it into the next dispatch to that agent.
736
+
575
737
  ### Escalation
576
738
  - Subjective or ambiguous items -> `operations/needs-human-review.md`
577
739
  - Never guess on product decisions — escalate