@alxyrgin/agent-forge 1.0.0 → 3.0.0

package/README.md

@@ -2,18 +2,18 @@
 
 AI-driven Development Framework for Claude Code.
 
-Scaffold a complete development infrastructure with Memory Bank, specialized agents, skills, and development rules in any project.
+Scaffold a complete development infrastructure with Memory Bank, specialized agents, skills, hooks, checkpoint system, and development rules in any project.
 
 ## Quick Start
 
 ```bash
-npx agent-forge init
+npx @alxyrgin/agent-forge init
 ```
 
 This creates a full AI-driven development infrastructure in your project:
 
-- **`.claude/`** — CLAUDE.md (Team Lead instructions), 8 agents, 7 skills, 3 rules
-- **`dev-infra/memory/`** — 8 Memory Bank files for persistent context
+- **`.claude/`** — CLAUDE.md (Team Lead instructions), 5-20 agents, 10-21 skills, 8 rules, hooks
+- **`dev-infra/memory/`** — 9 Memory Bank files for persistent context (incl. checkpoint)
 - **`dev-infra/tasks/`** — Task tracking system (tasks.json)
 - **`dev-infra/sessions/`** — Session logs
 - **`dev-infra/tests/`** — Test structure (acceptance, PMI, results)
@@ -22,7 +22,7 @@ This creates a full AI-driven development infrastructure in your project:
 
 ### Memory Bank
 
-8 markdown files that persist context across sessions:
+9 markdown files that persist context across sessions:
 
 | File | Purpose |
 |------|---------|
@@ -31,68 +31,112 @@ This creates a full AI-driven development infrastructure in your project:
 | `project-brief.md` | Project overview, team, stack |
 | `decisions.md` | Architectural Decision Records (ADR) |
 | `tech-stack.md` | Technology stack details |
-| `tech-debt.md` | Technical debt registry |
+| `tech-debt.md` | Technical debt registry with lifecycle tracking |
 | `patterns.md` | Code patterns and conventions |
 | `troubleshooting.md` | Problem solutions log |
+| `checkpoint.yml` | Recovery checkpoint for interrupted sessions |
 
 ### Agents
 
-Specialized AI agents, each with a specific role:
+20 specialized AI agents organized in 4 categories:
 
-| Agent | Role |
-|-------|------|
-| `analyst` | Requirement analysis from docs |
-| `architect` | Module architecture design |
-| `developer` | Code implementation |
-| `unit-tester` | Unit test writing and running |
-| `reviewer` | Code quality review |
-| `security-auditor` | Security and access control audit |
-| `doc-writer` | Documentation generation |
-| `progress-tracker` | Memory bank and task updates |
+| Category | Agents | Count |
+|----------|--------|-------|
+| Pipeline | analyst, architect, skeptic, developer, tester, inspector, reviewer, planner | 8 |
+| Planning | researcher, validator, interviewer, decomposer | 4 |
+| Security | auditor, prompter, deployer, scaffolder | 4 |
+| Documentation | librarian, writer, gatekeeper, verifier | 4 |
 
-**Full preset** adds: `planner`, `integration-tester`, `acceptance-tester`
-
-**Minimal preset** includes only: `analyst`, `developer`, `unit-tester`, `reviewer`
+**Preset coverage:**
+- **minimal** (5 agents) — analyst, developer, tester, inspector, reviewer
+- **core** (8 agents) — full pipeline category
+- **full** (20 agents) — all categories
 
 ### Skills (Slash Commands)
 
+#### Core skills (all presets) — 10
+
 | Command | Description |
 |---------|-------------|
-| `/start-session` | Begin work: sync repo, load context, show progress |
-| `/end-session` | Save context, create session log, commit & push |
-| `/take-task [id]` | Full development cycle: analysis -> code -> test -> review |
-| `/complete-task [id]` | Verify task completion, update progress |
+| `/start-session` | Begin work: sync repo, check checkpoint, load context, show progress |
+| `/end-session` | Save context, checkpoint, create session log, commit & push |
+| `/take-task [id]` | Full development cycle with feature-size routing (S/M/L) |
+| `/complete-task [id]` | Verify task, smoke test, update progress, clear checkpoint |
 | `/status` | Show project status, deadlines, blockers |
 | `/plan [mode]` | Plan/replan/validate tasks from documentation |
 | `/review [file]` | Code review for file or task |
+| `/code [task]` | Direct code generation for a specific task |
+| `/test [target]` | Run or generate tests for a target |
+| `/done [id]` | Quick-complete a task with minimal ceremony |
 
-### Development Cycle
+#### Extra skills (full preset only) — 11
 
-When you run `/take-task`, the system automatically orchestrates:
+| Command | Description |
+|---------|-------------|
+| `/interview` | Structured discovery interview (3 cycles, completeness >= 85%) |
+| `/audit-wave` | Comprehensive pre-milestone audit with GO/NO-GO verdict |
+| `/write-report` | Generate non-technical progress report for stakeholders |
+| `/dashboard` | Project dashboard: progress, health, tech debt, activity |
+| `/skill-master [name]` | Create a new custom skill from template |
+| `/decompose [task]` | Break down a task into subtasks |
+| `/feature [name]` | Scaffold a new feature end-to-end |
+| `/security [target]` | Run security analysis on a target |
+| `/spec [feature]` | Generate specification for a feature |
+| `/techspec [module]` | Generate technical specification for a module |
+| `/prompts [agent]` | Manage and optimize agent prompts |
 
-```
-[1] ANALYSIS    — analyst reads docs, finds requirements
-[2] DISCOVERY   — clarifying questions if unclear
-[3] PLAN        — architect designs module structure
-[4] CODE        — developer writes code
-[5] TESTS       — unit-tester writes tests (>=80% coverage)
-[6] REVIEW      — reviewer checks quality and security
-[7] FIXATION    — update tasks, progress, propose commit
-[8] TECH-DEBT   — record any deviations
-```
+### Feature-size Routing
+
+Tasks are automatically classified and routed through the appropriate pipeline:
+
+| Size | Criteria | Steps |
+|------|----------|-------|
+| **S** | 1 file, < 50 lines | checkpoint → code → tester+inspector → quick-review → tech-debt → fixation (6 steps) |
+| **M** | 2-5 files, new module | checkpoint → analysis → TDD(RED) → code+tester+inspector → review → tech-debt → fixation (8 steps) |
+| **L** | 6+ files, architecture changes | full cycle with architect, skeptic, per-feature loops, inspector, multi-round review (10 steps) |
+
+### Checkpoint System
+
+The checkpoint system (`dev-infra/memory/checkpoint.yml`) enables recovery after session interruptions:
+
+- **Automatic saving** — checkpoint is updated after each pipeline step
+- **Recovery on start** — `/start-session` detects active checkpoint and offers to resume
+- **Cleanup on completion** — `/complete-task` clears the checkpoint
+
+### Hooks
+
+- **`protect-docs.sh`** — PreToolUse hook that blocks Edit/Write operations in `docs/` directory
+- **Stop hook** — Reminds to save checkpoint and run `/end-session` before exiting
+
+### Rules
+
+8 development standards enforced automatically:
+
+| Rule | Purpose |
+|------|---------|
+| `commit-conventions` | Commit message format and style |
+| `development-cycle` | Feature-size routing and pipeline steps |
+| `testing-standards` | Test coverage and quality requirements |
+| `shared-resources` | Singleton resource registry and patterns |
+| `context-loading` | Just-in-time context loading, anti-patterns |
+| `agent-output-format` | JSON output standard for all agents |
+| `quality-gates` | Verdict-based routing and quality checkpoints |
+| `rollback-protocol` | Rollback procedures for failed deployments |
 
 ## Configuration
 
 ### Agent Presets
 
-- **Core** (default, 8 agents) — balanced set for most projects
-- **Full** (11 agents) — adds planner, integration tester, acceptance tester
-- **Minimal** (4 agents) — analyst, developer, unit-tester, reviewer
+| Preset | Agents | Skills | Description |
+|--------|--------|--------|-------------|
+| **minimal** | 5 | 10 | Essentials + inspector |
+| **core** (default) | 8 | 10 | Full development pipeline |
+| **full** | 20 | 21 | All categories + extra skills |
 
 ### Interactive Setup
 
 ```bash
-npx agent-forge init
+npx @alxyrgin/agent-forge init
 ```
 
 Prompts for:
@@ -107,7 +151,7 @@ Prompts for:
 ### Non-interactive
 
 ```bash
-npx agent-forge init --yes  # Use defaults
+npx @alxyrgin/agent-forge init --yes  # Use defaults
 ```
 
 ## Commands
@@ -132,24 +176,33 @@ Verifies all expected files exist and are not empty.
 your-project/
 ├── .claude/
 │   ├── CLAUDE.md              # Team Lead instructions
-│   ├── settings.json          # Claude Code hooks
-│   ├── agents/                # 4-11 specialized agents
-│   │   ├── analyst.md
-│   │   ├── architect.md
-│   │   ├── developer.md
-│   │   └── ...
-│   ├── skills/                # 7 slash commands
+│   ├── settings.json          # Claude Code hooks & env
+│   ├── hooks/
+│   │   └── protect-docs.sh    # PreToolUse hook
+│   ├── agents/                # 5-20 specialized agents (4 categories)
+│   │   ├── pipeline/          # analyst, architect, skeptic, developer,
+│   │   │                      # tester, inspector, reviewer, planner
+│   │   ├── planning/          # researcher, validator, interviewer, decomposer
+│   │   ├── security/          # auditor, prompter, deployer, scaffolder
+│   │   └── documentation/     # librarian, writer, gatekeeper, verifier
+│   ├── skills/                # 10-21 slash commands
 │   │   ├── start-session/SKILL.md
 │   │   ├── take-task/SKILL.md
 │   │   └── ...
-│   └── rules/                 # 3 development standards
+│   └── rules/                 # 8 development standards
 │       ├── commit-conventions.md
 │       ├── development-cycle.md
-│       └── testing-standards.md
+│       ├── testing-standards.md
+│       ├── shared-resources.md
+│       ├── context-loading.md
+│       ├── agent-output-format.md
+│       ├── quality-gates.md
+│       └── rollback-protocol.md
 ├── dev-infra/
-│   ├── memory/                # 8 Memory Bank files
+│   ├── memory/                # 9 Memory Bank files
 │   │   ├── active-context.md
 │   │   ├── progress.md
+│   │   ├── checkpoint.yml
 │   │   └── ...
 │   ├── tasks/
 │   │   └── tasks.json         # Task tracking

package/dist/index.js

@@ -181,9 +181,9 @@ async function promptProjectSetup(targetDir) {
       name: "agentPreset",
       message: "Agent preset:",
       choices: [
-        { name: "Core (8 agents \u2014 recommended)", value: "core" },
-        { name: "Full (11 agents)", value: "full" },
-        { name: "Minimal (4 agents)", value: "minimal" }
+        { name: "Core (8 agents \u2014 development pipeline)", value: "core" },
+        { name: "Full (20 agents \u2014 all categories + extra skills)", value: "full" },
+        { name: "Minimal (5 agents \u2014 essentials + inspector)", value: "minimal" }
       ]
     },
     {
@@ -276,6 +276,9 @@ async function fileExists(filePath) {
 async function readFile(filePath) {
   return fs.readFile(filePath, "utf-8");
 }
+async function makeExecutable(filePath) {
+  await fs.chmod(filePath, 493);
+}
 
 // src/utils/template.ts
 import fs2 from "fs";
@@ -302,7 +305,8 @@ var MEMORY_FILES = [
   "tech-stack.md",
   "tech-debt.md",
   "patterns.md",
-  "troubleshooting.md"
+  "troubleshooting.md",
+  "checkpoint.yml"
 ];
 async function generateMemoryBank(ctx, overwrite) {
   const result = {
@@ -333,39 +337,82 @@ async function generateMemoryBank(ctx, overwrite) {
 
 // src/generators/agents.ts
 import path4 from "path";
-var CORE_AGENTS = [
+var PIPELINE_AGENTS = [
   "analyst",
   "architect",
+  "skeptic",
   "developer",
-  "unit-tester",
+  "tester",
+  "inspector",
   "reviewer",
-  "security-auditor",
-  "doc-writer",
-  "progress-tracker"
+  "planner"
+];
+var PLANNING_AGENTS = [
+  "researcher",
+  "validator",
+  "interviewer",
+  "decomposer"
+];
+var SECURITY_AGENTS = [
+  "auditor",
+  "prompter",
+  "deployer",
+  "scaffolder"
 ];
-var EXTRA_AGENTS = [
-  "planner",
-  "integration-tester",
-  "acceptance-tester"
+var DOCUMENTATION_AGENTS = [
+  "librarian",
+  "writer",
+  "gatekeeper",
+  "verifier"
 ];
 var MINIMAL_AGENTS = [
   "analyst",
   "developer",
-  "unit-tester",
-  "reviewer"
+  "tester",
+  "reviewer",
+  "inspector"
+];
+var CORE_AGENTS = [...PIPELINE_AGENTS];
+var FULL_AGENTS = [
+  ...PIPELINE_AGENTS,
+  ...PLANNING_AGENTS,
+  ...SECURITY_AGENTS,
+  ...DOCUMENTATION_AGENTS
 ];
+var CATEGORY_MAP = {};
+for (const name of PIPELINE_AGENTS) {
+  CATEGORY_MAP[name] = "pipeline";
+}
+for (const name of PLANNING_AGENTS) {
+  CATEGORY_MAP[name] = "planning";
+}
+for (const name of SECURITY_AGENTS) {
+  CATEGORY_MAP[name] = "security";
+}
+for (const name of DOCUMENTATION_AGENTS) {
+  CATEGORY_MAP[name] = "documentation";
+}
+function getAgentCategory(name) {
+  return CATEGORY_MAP[name] || "pipeline";
+}
 function getAgentList(preset) {
-  const agents = [];
-  const coreList = preset === "minimal" ? MINIMAL_AGENTS : CORE_AGENTS;
-  for (const name of coreList) {
-    agents.push({ name, dir: "core" });
+  let names;
+  switch (preset) {
+    case "minimal":
+      names = MINIMAL_AGENTS;
+      break;
+    case "full":
+      names = FULL_AGENTS;
+      break;
+    case "core":
+    default:
+      names = CORE_AGENTS;
+      break;
   }
-  if (preset === "full") {
-    for (const name of EXTRA_AGENTS) {
-      agents.push({ name, dir: "extra" });
-    }
-  }
-  return agents;
+  return names.map((name) => ({
+    name,
+    category: getAgentCategory(name)
+  }));
 }
 async function generateAgents(ctx, overwrite) {
   const result = {
@@ -381,7 +428,7 @@ async function generateAgents(ctx, overwrite) {
   for (const agent of agents) {
     try {
       const content = await renderTemplate(
-        `agents/${agent.dir}/${agent.name}.md.ejs`,
+        `agents/${agent.category}/${agent.name}.md.ejs`,
         templateData
       );
       const outputPath = path4.join(ctx.targetDir, ".claude/agents", `${agent.name}.md`);
@@ -400,15 +447,43 @@ async function generateAgents(ctx, overwrite) {
 
 // src/generators/skills.ts
 import path5 from "path";
-var SKILLS = [
+var CORE_SKILLS = [
   "start-session",
   "end-session",
   "take-task",
   "complete-task",
   "status",
   "plan",
-  "review"
+  "review",
+  "code",
+  "test",
+  "done"
+];
+var EXTRA_SKILLS = [
+  "interview",
+  "audit-wave",
+  "write-report",
+  "dashboard",
+  "skill-master",
+  "decompose",
+  "feature",
+  "security",
+  "spec",
+  "techspec",
+  "prompts"
 ];
+function getSkillList(preset) {
+  const skills = [];
+  for (const name of CORE_SKILLS) {
+    skills.push({ name, dir: "core" });
+  }
+  if (preset === "full") {
+    for (const name of EXTRA_SKILLS) {
+      skills.push({ name, dir: "extra" });
+    }
+  }
+  return skills;
+}
 async function generateSkills(ctx, overwrite) {
   const result = {
     filesCreated: [],
@@ -419,13 +494,14 @@ async function generateSkills(ctx, overwrite) {
     ...ctx,
     defaultBranch: "main"
   };
-  for (const skill of SKILLS) {
+  const skills = getSkillList(ctx.agentPreset);
+  for (const skill of skills) {
     try {
       const content = await renderTemplate(
-        `skills/core/${skill}/SKILL.md.ejs`,
+        `skills/${skill.dir}/${skill.name}/SKILL.md.ejs`,
         templateData
       );
-      const outputPath = path5.join(ctx.targetDir, `.claude/skills/${skill}`, "SKILL.md");
+      const outputPath = path5.join(ctx.targetDir, `.claude/skills/${skill.name}`, "SKILL.md");
       const status = await writeFileSafe(outputPath, content, overwrite);
       if (status === "skipped") {
         result.filesSkipped.push(outputPath);
@@ -433,7 +509,7 @@ async function generateSkills(ctx, overwrite) {
         result.filesCreated.push(outputPath);
       }
     } catch (err) {
-      result.errors.push(`Skill ${skill}: ${err}`);
+      result.errors.push(`Skill ${skill.name}: ${err}`);
     }
   }
   return result;
@@ -444,7 +520,12 @@ import path6 from "path";
 var RULES = [
   "commit-conventions",
   "development-cycle",
-  "testing-standards"
+  "testing-standards",
+  "shared-resources",
+  "context-loading",
+  "agent-output-format",
+  "quality-gates",
+  "rollback-protocol"
 ];
 async function generateRules(ctx, overwrite) {
   const result = {
@@ -559,7 +640,7 @@ async function generateInfra(ctx, overwrite) {
   }
   try {
     const manifest = {
-      version: "1.0.0",
+      version: "3.0.0",
       createdAt: ctx.today,
       projectName: ctx.projectName,
       agentPreset: ctx.agentPreset,
@@ -595,44 +676,105 @@ function getExpectedFiles(ctx) {
     "dev-infra/memory/tech-stack.md",
     "dev-infra/memory/tech-debt.md",
     "dev-infra/memory/patterns.md",
-    "dev-infra/memory/troubleshooting.md"
+    "dev-infra/memory/troubleshooting.md",
+    "dev-infra/memory/checkpoint.yml"
   ];
+  files.push(".claude/hooks/protect-docs.sh");
   files.push(
     ".claude/rules/commit-conventions.md",
     ".claude/rules/development-cycle.md",
-    ".claude/rules/testing-standards.md"
+    ".claude/rules/testing-standards.md",
+    ".claude/rules/shared-resources.md",
+    ".claude/rules/context-loading.md",
+    ".claude/rules/agent-output-format.md",
+    ".claude/rules/quality-gates.md",
+    ".claude/rules/rollback-protocol.md"
   );
-  const skills = [
+  const coreSkills = [
     "start-session",
     "end-session",
     "take-task",
     "complete-task",
     "status",
     "plan",
-    "review"
+    "review",
+    "code",
+    "test",
+    "done"
+  ];
+  const extraSkills = [
+    "interview",
+    "audit-wave",
+    "write-report",
+    "dashboard",
+    "skill-master",
+    "decompose",
+    "feature",
+    "security",
+    "spec",
+    "techspec",
+    "prompts"
   ];
+  const skills = ctx.agentPreset === "full" ? [...coreSkills, ...extraSkills] : coreSkills;
   for (const skill of skills) {
     files.push(`.claude/skills/${skill}/SKILL.md`);
   }
-  const coreAgents = [
+  const pipelineAgents = [
     "analyst",
     "architect",
+    "skeptic",
     "developer",
-    "unit-tester",
+    "tester",
+    "inspector",
     "reviewer",
-    "security-auditor",
-    "doc-writer",
-    "progress-tracker"
+    "planner"
   ];
-  const minimalAgents = ["analyst", "developer", "unit-tester", "reviewer"];
-  const extraAgents = ["planner", "integration-tester", "acceptance-tester"];
-  const agents = ctx.agentPreset === "minimal" ? minimalAgents : ctx.agentPreset === "full" ? [...coreAgents, ...extraAgents] : coreAgents;
+  const planningAgents = ["researcher", "validator", "interviewer", "decomposer"];
+  const securityAgents = ["auditor", "prompter", "deployer", "scaffolder"];
+  const documentationAgents = ["librarian", "writer", "gatekeeper", "verifier"];
+  const minimalAgents = ["analyst", "developer", "tester", "reviewer", "inspector"];
+  const coreAgents = [...pipelineAgents];
+  const fullAgents = [
+    ...pipelineAgents,
+    ...planningAgents,
+    ...securityAgents,
+    ...documentationAgents
+  ];
+  const agents = ctx.agentPreset === "minimal" ? minimalAgents : ctx.agentPreset === "full" ? fullAgents : coreAgents;
   for (const agent of agents) {
     files.push(`.claude/agents/${agent}.md`);
   }
   return files;
 }
 
+// src/generators/hooks.ts
+import path9 from "path";
+async function generateHooks(ctx, overwrite) {
+  const result = {
+    filesCreated: [],
+    filesSkipped: [],
+    errors: []
+  };
+  const templateData = {
+    ...ctx,
+    defaultBranch: "main"
+  };
+  try {
+    const content = await renderTemplate("hooks/protect-docs.sh.ejs", templateData);
+    const outputPath = path9.join(ctx.targetDir, ".claude/hooks/protect-docs.sh");
+    const status = await writeFileSafe(outputPath, content, overwrite);
+    if (status === "skipped") {
+      result.filesSkipped.push(outputPath);
+    } else {
+      result.filesCreated.push(outputPath);
+      await makeExecutable(outputPath);
+    }
+  } catch (err) {
+    result.errors.push(`Hook protect-docs.sh: ${err}`);
+  }
+  return result;
+}
+
 // src/generators/index.ts
 async function generateAll(ctx, overwrite = false) {
   const result = {
@@ -646,6 +788,7 @@ async function generateAll(ctx, overwrite = false) {
     generateSkills,
     generateRules,
     generateMemoryBank,
+    generateHooks,
     generateInfra
   ];
   for (const generator of generators) {
@@ -665,7 +808,7 @@ async function generateAll(ctx, overwrite = false) {
 async function initCommand(options) {
   const targetDir = process.cwd();
   console.log();
-  console.log(chalk.bold("  agent-forge v1.0.0"));
+  console.log(chalk.bold("  agent-forge v3.0.0"));
   console.log(chalk.dim("  AI-driven Development Framework for Claude Code"));
   console.log();
   let ctx;
@@ -708,7 +851,7 @@ async function initCommand(options) {
 }
 
 // src/commands/doctor.ts
-import path9 from "path";
+import path10 from "path";
 import chalk2 from "chalk";
 async function doctorCommand() {
   const targetDir = process.cwd();
@@ -716,7 +859,7 @@ async function doctorCommand() {
   console.log(chalk2.bold("  agent-forge doctor"));
   console.log(chalk2.dim("  Checking project structure integrity..."));
   console.log();
-  const manifestPath = path9.join(targetDir, ".claude-forge.json");
+  const manifestPath = path10.join(targetDir, ".claude-forge.json");
   const manifestExists = await fileExists(manifestPath);
   if (!manifestExists) {
     console.log(chalk2.red("  .claude-forge.json not found"));
@@ -739,7 +882,7 @@ async function doctorCommand() {
   let okCount = 0;
   let failCount = 0;
   for (const file of manifest.expectedFiles) {
-    const filePath = path9.join(targetDir, file);
+    const filePath = path10.join(targetDir, file);
     const exists = await fileExists(filePath);
     const check = {
       name: file,
@@ -801,7 +944,7 @@ async function doctorCommand() {
 
 // src/index.ts
 var program = new Command();
-program.name("agent-forge").description("AI-driven Development Framework for Claude Code").version("1.0.0");
+program.name("agent-forge").description("AI-driven Development Framework for Claude Code").version("3.0.0");
 program.command("init").description("Initialize AI-driven development infrastructure in the current project").option("-y, --yes", "Skip prompts and use defaults").option("--overwrite", "Overwrite existing files").action(initCommand);
 program.command("doctor").description("Check integrity of the generated structure").action(doctorCommand);
 program.parse();