ai-driven-skills 0.1.0

package/README.md

@@ -0,0 +1,140 @@
+# ai-driven-skills
+
+AI-driven incremental development for [Claude Code](https://claude.com/claude-code). Six slash commands that turn a Claude Code session into a self-driving project loop: bootstrap a project skeleton, plan the next task, build it, verify it, archive it — and optionally repeat until the roadmap is exhausted.
+
+Lighter than PRD/ADR/issue ceremony. Heavier than vibe-coding. Designed for one human + one agent on one repo.
+
+```
+/init-arch  →  /plan-next  →  /verify  →  /report
+                    ↓
+                 /auto  (loop /plan-next until done)
+                    ↓
+              /sync-arch  (reconcile docs ↔ code when drifted)
+```
+
+## Install
+
+### Globally (recommended)
+
+```bash
+npx ai-driven-skills@latest install
+```
+
+Installs to `~/.claude/skills/` so the commands are available in every project.
+
+### Per project
+
+```bash
+npx ai-driven-skills@latest install --project
+```
+
+Installs to `./.claude/skills/` in the current directory only.
+
+### Other commands
+
+```bash
+npx ai-driven-skills@latest list           # show what's installed where
+npx ai-driven-skills@latest install -f     # overwrite existing files
+npx ai-driven-skills@latest uninstall      # remove all 6 skills
+npx ai-driven-skills@latest help
+```
+
+After installing, restart Claude Code (or run `/help`) so the new slash commands are picked up.
+
+## What you get
+
+| Command | Purpose |
+|---|---|
+| `/init-arch`  | Bootstrap the project skeleton: `ARCHITECTURE.md`, `DONT.md`, `ROADMAP.md`, `STATE.md`, `verify.sh`, `tasks/`. Interactive grilling for new projects, reverse-engineering for existing ones. |
+| `/plan-next`  | Drive **one** task end-to-end: pick from ROADMAP → generate PRD + verify.sh → implement → verify → archive. |
+| `/auto`       | Loop `/plan-next` until ROADMAP is exhausted or a stop condition halts. Skips `🛑 needs-review` and `HITL` markers. |
+| `/verify`     | Run task verify + project verify on demand. Read-only, no fixes. |
+| `/sync-arch`  | Reconcile `ARCHITECTURE.md` / `DONT.md` / `ROADMAP.md` with the current code. Proposes diffs, applies on confirmation. |
+| `/report`     | Print a project status snapshot. Read-only. |
+
+## How it works
+
+The skills share four state files at the project root:
+
+- **`ARCHITECTURE.md`** — modules, tech stack, conventions
+- **`DONT.md`** — hard constraints, things never to do
+- **`ROADMAP.md`** — task list with statuses (`[ ]`, `[~]`, `[x]`, `🛑 needs-review`, `HITL`)
+- **`STATE.md`** — current task, last verify, recent decisions
+
+Plus:
+
+- **`verify.sh`** — project-level regression check (tests, lint, build)
+- **`tasks/NNN-<type>-<slug>/`** — per-task PRD, verify.sh, report.md, CHANGES.md
+
+Tasks are stored in numbered directories (`001-feature-foo/`, `002-bug-bar/`, …). The "current task" is just a field in `STATE.md` — no symlinks, so this works on macOS, Linux, and Windows.
+
+## Typical workflow
+
+```bash
+# 1. Bootstrap (once per project)
+/init-arch
+
+# 2. Drive one task at a time
+/plan-next
+
+# 3. Or let it run hands-off
+/auto
+
+# 4. Spot-check anytime
+/verify
+/report
+
+# 5. Reconcile when docs drift from code
+/sync-arch
+```
+
+## Stop conditions (the safety net)
+
+`/plan-next` and `/auto` halt instead of papering over problems when:
+
+- Required state files are missing
+- Same test fails 3+ times
+- A task would touch `DONT.md`-protected code
+- A task is marked `🛑 needs-review` or `HITL`
+- More than 10 files would be modified
+- Project `verify.sh` fails after a task verify passes (regression detected)
+
+You always get a clear halt message — never silent retry, never silent rewrite of constraints.
+
+## Cross-platform
+
+- Pure Node.js CLI (no native deps)
+- No symlinks (Windows-friendly)
+- File copy install / removal — no shell tricks
+- Works with Node 14+
+
+## For maintainers — publishing to npm
+
+```bash
+# 1. Login (once per machine)
+npm login
+
+# 2. Verify package contents
+npm pack --dry-run
+
+# 3. Bump version
+npm version patch   # or minor / major
+
+# 4. Publish
+npm publish --access public
+
+# 5. Verify
+npx ai-driven-skills@latest help
+```
+
+Pre-publish checklist:
+
+- [ ] All 6 skills present in `skills/`
+- [ ] `bin/cli.js` runs without error: `node bin/cli.js help`
+- [ ] `npm pack --dry-run` shows only `bin/`, `skills/`, `README.md`, `package.json`
+- [ ] `repository.url` in `package.json` points to the real repo
+- [ ] Bumped `version` field
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+/**
+ * ai-driven-skills CLI
+ *
+ * Cross-platform installer for the 6 AI-driven development skills.
+ * Copies SKILL.md files into the user's Claude Code skills directory.
+ *
+ * Usage:
+ *   npx ai-driven-skills install [--global|--project] [--force]
+ *   npx ai-driven-skills uninstall [--global|--project]
+ *   npx ai-driven-skills list
+ *   npx ai-driven-skills help
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SKILL_NAMES = ['init-arch', 'plan-next', 'auto', 'verify', 'sync-arch', 'report'];
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const SKILLS_SRC = path.join(PACKAGE_ROOT, 'skills');
+
+function parseArgs(argv) {
+  const args = { command: null, scope: 'global', force: false };
+  for (const a of argv.slice(2)) {
+    if (a === '--global') args.scope = 'global';
+    else if (a === '--project') args.scope = 'project';
+    else if (a === '--force' || a === '-f') args.force = true;
+    else if (!args.command) args.command = a;
+  }
+  return args;
+}
+
+function getTargetDir(scope) {
+  if (scope === 'project') {
+    return path.join(process.cwd(), '.claude', 'skills');
+  }
+  return path.join(os.homedir(), '.claude', 'skills');
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function copyFile(src, dest) {
+  fs.copyFileSync(src, dest);
+}
+
+function rmrf(target) {
+  if (!fs.existsSync(target)) return;
+  fs.rmSync(target, { recursive: true, force: true });
+}
+
+function cmdInstall(scope, force) {
+  const targetRoot = getTargetDir(scope);
+  ensureDir(targetRoot);
+
+  console.log(`Installing ai-driven-skills (${scope}) → ${targetRoot}`);
+
+  let installed = 0;
+  let skipped = 0;
+
+  for (const name of SKILL_NAMES) {
+    const srcSkill = path.join(SKILLS_SRC, name, 'SKILL.md');
+    const destDir = path.join(targetRoot, name);
+    const destSkill = path.join(destDir, 'SKILL.md');
+
+    if (!fs.existsSync(srcSkill)) {
+      console.warn(`  ! source missing: ${name} (skipped)`);
+      continue;
+    }
+
+    if (fs.existsSync(destSkill) && !force) {
+      console.log(`  - ${name}: already installed (use --force to overwrite)`);
+      skipped++;
+      continue;
+    }
+
+    ensureDir(destDir);
+    copyFile(srcSkill, destSkill);
+    console.log(`  + ${name}`);
+    installed++;
+  }
+
+  console.log('');
+  console.log(`Done. ${installed} installed, ${skipped} skipped.`);
+  if (installed > 0) {
+    console.log('');
+    console.log('Restart Claude Code (or reload skills) to pick up the new commands:');
+    console.log('  /init-arch   — bootstrap project skeleton');
+    console.log('  /plan-next   — drive one task end-to-end');
+    console.log('  /auto        — loop /plan-next until ROADMAP exhausted');
+    console.log('  /verify      — run task + project verify');
+    console.log('  /sync-arch   — reconcile docs with code');
+    console.log('  /report      — print project status');
+  }
+}
+
+function cmdUninstall(scope) {
+  const targetRoot = getTargetDir(scope);
+  console.log(`Uninstalling ai-driven-skills (${scope}) ← ${targetRoot}`);
+
+  let removed = 0;
+  for (const name of SKILL_NAMES) {
+    const dir = path.join(targetRoot, name);
+    if (fs.existsSync(dir)) {
+      rmrf(dir);
+      console.log(`  - ${name}`);
+      removed++;
+    }
+  }
+  console.log('');
+  console.log(`Done. ${removed} removed.`);
+}
+
+function cmdList() {
+  const globalDir = getTargetDir('global');
+  const projectDir = getTargetDir('project');
+
+  console.log('ai-driven-skills — installation status');
+  console.log('');
+  for (const [scope, dir] of [['global', globalDir], ['project', projectDir]]) {
+    console.log(`[${scope}] ${dir}`);
+    for (const name of SKILL_NAMES) {
+      const installed = fs.existsSync(path.join(dir, name, 'SKILL.md'));
+      console.log(`  ${installed ? '✓' : ' '} ${name}`);
+    }
+    console.log('');
+  }
+}
+
+function cmdHelp() {
+  console.log(`ai-driven-skills — AI-driven incremental development for Claude Code
+
+Usage:
+  npx ai-driven-skills <command> [options]
+
+Commands:
+  install      Install all 6 skills into Claude Code's skills directory
+  uninstall    Remove the 6 skills
+  list         Show which skills are currently installed
+  help         Show this message
+
+Options:
+  --global     Target ~/.claude/skills/ (default)
+  --project    Target ./.claude/skills/ in current directory
+  --force, -f  Overwrite existing files on install
+
+Examples:
+  npx ai-driven-skills install
+  npx ai-driven-skills install --project
+  npx ai-driven-skills install --force
+  npx ai-driven-skills uninstall --project
+  npx ai-driven-skills list
+
+Skills installed:
+  init-arch · plan-next · auto · verify · sync-arch · report
+
+Cross-platform: works on macOS, Linux, and Windows (no symlinks used).
+`);
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  switch (args.command) {
+    case 'install':
+      return cmdInstall(args.scope, args.force);
+    case 'uninstall':
+    case 'remove':
+      return cmdUninstall(args.scope);
+    case 'list':
+    case 'ls':
+      return cmdList();
+    case 'help':
+    case '--help':
+    case '-h':
+    case null:
+      return cmdHelp();
+    default:
+      console.error(`Unknown command: ${args.command}`);
+      console.error(`Run "npx ai-driven-skills help" for usage.`);
+      process.exit(1);
+  }
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "ai-driven-skills",
+  "version": "0.1.0",
+  "description": "AI-driven incremental development skills for Claude Code: init-arch, plan-next, auto, verify, sync-arch, report.",
+  "bin": {
+    "ai-driven-skills": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "skills",
+    "ai",
+    "agent",
+    "automation"
+  ],
+  "license": "MIT"
+}

package/skills/auto/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: auto
+description: Continuous AI-driven development. Loops `/plan-next` until ROADMAP is exhausted or a stop condition fires. Use when the user wants the project to advance hands-off across multiple tasks. Honors HITL / 🛑 needs-review markers and halts on regressions.
+---
+
+<what-to-do>
+
+Run `/plan-next` repeatedly until the ROADMAP is exhausted or a stop condition halts the loop.
+
+The user's intent: they want the project to keep moving without re-prompting after each task. They've already initialized the skeleton (`/init-arch`) and seeded ROADMAP.md. Your job is to drive task after task, surface progress concisely, and stop the moment something needs human attention — never paper over a failure to keep the loop alive.
+
+Run the loop steps below. Do not skip stop checks. The user can Ctrl+C at any time.
+
+</what-to-do>
+
+<supporting-info>
+
+## Step 0 — Preflight
+
+Before entering the loop, confirm:
+
+1. `STATE.md`, `ROADMAP.md`, `DONT.md` all exist. If missing → halt, tell user to run `/init-arch`.
+2. `STATE.md` `current_task` is `null`. If a task is already in-progress → halt and ask whether to resume it (`/plan-next` will resume) or abandon and reset.
+3. ROADMAP "Up next" has at least one task that is not `🛑 needs-review` and not `HITL`. Otherwise → halt with reason.
+
+Parse optional flags:
+- `--max N` — stop after N tasks completed (default: unlimited until ROADMAP exhausted)
+- `--include-hitl` — also process tasks marked `HITL` (default: skip them)
+- `--dry-run` — print what would be done, don't execute
+
+## Step 1 — Loop
+
+For each iteration:
+
+1. **Check stop conditions** (see table below). If any fire → halt with reason.
+2. **Pick next eligible task** from ROADMAP "Up next":
+   - Skip tasks marked `🛑 needs-review` (record them in a "skipped" list for the final summary)
+   - Skip tasks marked `HITL` unless `--include-hitl`
+   - If no eligible task remains → exit loop with "ROADMAP exhausted (or all remaining require human)"
+3. **Invoke `/plan-next`** to drive that task through plan → build → verify → archive.
+4. **Read the result**:
+   - Success → print one-line summary: `✅ NNN-<type>-<slug> done (Xs build, Ys verify)`
+   - Halt from `/plan-next` (any stop condition) → propagate halt, do not retry
+5. **Increment counter**. If `--max N` reached → exit loop.
+
+Between iterations, do not pause or sleep — the user can interrupt.
+
+## Step 2 — Final summary
+
+When the loop exits (for any reason), print:
+
+```
+ai-driven-skills /auto session summary
+─────────────────────────────────────
+Completed: N tasks
+  - 001-feature-foo ✅
+  - 002-bug-bar ✅
+  - 003-refactor-baz ✅
+
+Skipped (needs-review / HITL): M tasks
+  - 004-feature-qux (🛑 needs-review)
+  - 005-feature-quux (HITL)
+
+Stopped because: <reason>
+
+Next:
+  <suggested action — e.g. "Resolve 🛑 markers, then re-run /auto"
+   or "ROADMAP exhausted — add new entries or run /sync-arch"
+   or "Verify failed on task NNN — see tasks/NNN-.../report.md">
+```
+
+## Stop conditions
+
+The loop halts immediately, without starting a new task, if any of these fire:
+
+| Condition | Reason |
+|---|---|
+| `/plan-next` halted with any stop condition | Propagate that halt — never retry blindly |
+| Project `verify.sh` failed (regression) | Critical — surface the failure, do not continue |
+| Same task type failed 2× in a row | Pattern suggests a systemic issue |
+| 3+ consecutive tasks needed `🛑 needs-review` after planning | Architecture is drifting — call `/sync-arch` |
+| ROADMAP "Up next" empty (all eligible tasks done) | Normal exhaustion |
+| `--max N` count reached | User-requested cap |
+| User-supplied `DONT.md` violation surfaced | Always halt — never auto-resolve constraint conflicts |
+| Unexpected error from any tool call | Halt with the error verbatim — don't swallow it |
+
+## Behavioral rules
+
+- **Never modify ROADMAP entries to dodge a halt.** If a task is `🛑 needs-review`, you skip it; you don't unmark it.
+- **Never lower the bar to make verify pass.** Don't disable tests, comment out checks, or relax acceptance criteria.
+- **Never edit `DONT.md` to make a planned change legal.** That's a halt — surface and ask.
+- **Never start a new task while `current_task` is set.** That signals an in-progress task — resume it, don't bypass.
+- Keep per-task output minimal — one line per task. Detailed reports already live in `tasks/NNN-.../report.md`.
+
+## When NOT to use this skill
+
+- ROADMAP has only one task → just run `/plan-next` directly.
+- User wants to review each task before the next starts → run `/plan-next --review` manually in a loop.
+- Project skeleton not initialized → use `/init-arch` first.
+- Architecture has drifted significantly → run `/sync-arch` before resuming auto-mode.
+
+</supporting-info>

package/skills/init-arch/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: init-arch
+description: Initialize the AI-driven-skills project skeleton — ARCHITECTURE.md, DONT.md, ROADMAP.md, STATE.md, verify.sh, tasks/. For new projects, run an interactive grilling session to build ARCHITECTURE. For existing projects, reverse-engineer a draft from the codebase. Use this once per project before any other ai-driven-skills command.
+---
+
+<what-to-do>
+
+Bootstrap the project so the rest of the ai-driven-skills toolkit (`/plan-next`, `/auto`, `/verify`, `/sync-arch`, `/report`) can operate.
+
+The user's intent: they want to start using AI-driven incremental development on either a fresh project or an existing codebase. They need the four state files and the `tasks/` directory in place. For new projects, the architecture is in their head — extract it through an interview. For existing projects, the architecture is in the code — extract it by reading.
+
+If any of the required files already exist, **do not overwrite them**. Halt and tell the user — they should either confirm overwrite explicitly or run `/sync-arch` to update specific files.
+
+</what-to-do>
+
+<supporting-info>
+
+## Step 0 — Detect project state
+
+Check whether the project is empty/new or has existing code:
+
+- **New project signals**: empty directory, only README.md, no source files
+- **Existing project signals**: has source files (`.py` / `.ts` / `.go` / `.kt` etc.), has `package.json` / `pyproject.toml` / similar
+
+Pick the appropriate path below.
+
+Also check for existing skeleton files:
+- `ARCHITECTURE.md`, `DONT.md`, `ROADMAP.md`, `STATE.md`, `verify.sh`, `tasks/`
+
+If **any** exist, halt and report which ones are present. Ask the user whether to:
+1. Skip init (use what's already there)
+2. Reinitialize specific files (they pick which)
+3. Cancel
+
+## Path A — New project (interactive grilling)
+
+The architecture isn't written down anywhere. Extract it by interviewing the user.
+
+Ask questions **one at a time**, waiting for the answer before continuing. For each question, recommend an answer based on what you already know.
+
+**Topics to cover, in order:**
+
+1. **One-line project purpose** — "What does this project do, in one sentence?"
+2. **Core domain concepts** — Probe for the 3-7 nouns/verbs that define the project. Watch for ambiguous terms that need disambiguation.
+3. **Module / component breakdown** — How does the user think about the major pieces? (modules, services, layers, contexts)
+4. **Hard constraints** — What's off-limits? Technologies that can't be used, decisions already made elsewhere, regulatory requirements. These become DONT.md.
+5. **Initial roadmap** — What are the first 3-10 things to build? In what order?
+
+After each answer, write to the appropriate file immediately (don't batch). Show the user what you wrote.
+
+## Path B — Existing project (reverse-engineering)
+
+The architecture is in the code. Extract a draft, then have the user correct it.
+
+**Steps:**
+
+1. **Survey the codebase** — Use the Explore agent or direct grep/find to map:
+   - Top-level directories and their apparent purpose
+   - Build / config files (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, etc.)
+   - Existing docs (`README.md`, `docs/`, `ARCHITECTURE.md` if any)
+   - Test directories
+   - Entry points (`main.py`, `index.ts`, etc.)
+
+2. **Draft ARCHITECTURE.md** — Based on the survey:
+   - One-line purpose (extract from README or infer from code)
+   - Module/component map (from directory structure)
+   - Tech stack (from build files)
+   - Conventions you can detect (test naming, file structure patterns)
+
+3. **Draft DONT.md** — Initially empty or with placeholder. Tell the user "I cannot detect implicit constraints from code alone. Please add hard rules here as we discover them."
+
+4. **Draft ROADMAP.md** — Initially with one entry: "Review and confirm initial architecture draft (`/sync-arch`)". The user adds real tasks afterward.
+
+5. **Present the drafts** to the user. Highlight specifically:
+   - "Here's what I inferred. Anything wrong?"
+   - "Here are areas where I had to guess. Please confirm or correct."
+
+6. **Iterate** based on user feedback. Update the files in place.
+
+## Files to create (both paths)
+
+### `ARCHITECTURE.md` template
+
+```markdown
+# Architecture
+
+## Purpose
+
+One paragraph describing what this project does and why.
+
+## Modules
+
+| Module | Purpose | Notes |
+|---|---|---|
+| <name> | <one line> | <key constraint or context> |
+
+## Tech stack
+
+- Language(s): <list>
+- Key frameworks/libraries: <list>
+- Storage: <list>
+- External services: <list>
+
+## Conventions
+
+- <convention 1>
+- <convention 2>
+
+## Sub-architecture docs
+
+For complex modules, link to deeper docs here:
+- `<module>/ARCHITECTURE.md` — <brief>
+```
+
+### `DONT.md` template
+
+```markdown
+# DON'T
+
+Hard constraints. Things never to do. Grep-friendly.
+
+Add entries as bullet points. Keep each entry one line. The reason in parentheses if non-obvious.
+
+## Examples (delete these once you have real entries)
+
+- DON'T modify files in `legacy/` — frozen on YYYY-MM-DD
+- DON'T add JSON schemas to `contracts/` unless they cross process boundaries
+- DON'T introduce new external dependencies without explicit approval
+```
+
+### `ROADMAP.md` template
+
+```markdown
+# Roadmap
+
+Status legend: `[ ]` not started · `[~]` in progress · `[x]` done · `🛑 needs-review` halt auto-mode here · `HITL` requires human
+
+## In progress
+
+(nothing yet)
+
+## Up next
+
+- [ ] 001-<type>-<slug> — <one-line description>
+- [ ] 002-<type>-<slug> — <one-line description>
+
+## Backlog
+
+- [ ] <type>-<slug> — <description>
+
+## Done
+
+(nothing yet)
+```
+
+### `STATE.md` template
+
+```markdown
+# State
+
+current_task: null
+last_completed: null
+last_verify: null
+next_planned: 001-<type>-<slug>
+blocked: none
+
+## Recent decisions (last 5)
+
+(none yet)
+```
+
+### `verify.sh` template
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Project-level verification — runs after every task to defend against regressions.
+# Add commands that should always pass: tests, lint, type-check, build.
+
+echo "Running project verification..."
+
+# Example:
+# pytest
+# npm test
+# cargo test
+
+echo "✅ Project verification passed"
+```
+
+Make `verify.sh` executable: `chmod +x verify.sh` (skip on Windows; mention in output).
+
+### `tasks/` directory
+
+Create empty `tasks/` directory. Optionally create `tasks/.gitkeep` so git tracks it.
+
+## Final summary
+
+After all files are written, print:
+
+```
+✅ ai-driven-skills project initialized.
+
+Files created:
+  ARCHITECTURE.md (X lines)
+  DONT.md
+  ROADMAP.md (N tasks queued)
+  STATE.md
+  verify.sh
+  tasks/
+
+Next steps:
+  1. Review ARCHITECTURE.md and ROADMAP.md
+  2. Add real entries to DONT.md as constraints become clear
+  3. Run `/plan-next` to start the first task
+  4. Or `/auto` to run continuously
+```
+
+## Stop conditions
+
+- User refuses to answer a grilling question → record what's known, leave gaps marked `<TBD>`, proceed
+- Existing skeleton files conflict → halt, ask before overwriting
+- Codebase too large to survey reasonably (>10k files) → halt, ask user to point at specific top-level dirs to focus on
+
+## When NOT to use this skill
+
+- Project is already initialized → use `/sync-arch` to update specific files
+- User just wants to add one task → edit ROADMAP.md directly, then `/plan-next`
+
+</supporting-info>

package/skills/plan-next/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: plan-next
+description: AI-driven incremental development. Reads STATE.md / ROADMAP.md / DONT.md, picks the next task, generates its PRD + verify.sh, implements it, verifies, and archives — all in one shot. Use when the user wants to advance the project by one task without manual planning ceremony.
+---
+
+<what-to-do>
+
+Drive one full task lifecycle: **plan → build → verify → archive**.
+
+The user's intent: they want forward motion without the overhead of writing PRDs, ADRs, and issues by hand. They have already set up the project skeleton (via `/init-arch`). You read the project state, decide what to do next, do it, verify it works, and archive the result. If anything is unclear or risky, stop and ask — don't guess.
+
+Run the steps below in order. Do not skip steps. If a step fails or surfaces a stop condition, halt immediately and report.
+
+</what-to-do>
+
+<supporting-info>
+
+## Step 0 — Mandatory context load
+
+Read these three files **first**, before doing anything else:
+
+1. `STATE.md` — current task, last completed, recent decisions
+2. `ROADMAP.md` — full task list with status, `🛑 needs-review` markers
+3. `DONT.md` — hard constraints, things never to do
+
+If any of these files is missing, halt and tell the user to run `/init-arch` first.
+
+If `STATE.md` shows `current_task` is set (i.e. an in-progress task exists), **do not plan a new task** — resume that one (jump to Step 2).
+
+## Step 1 — Plan
+
+Pick the next task by this priority:
+
+1. First task in ROADMAP's "Up next" section that is **not** marked `🛑 needs-review`
+2. If all "Up next" tasks are `needs-review`, halt and tell the user
+3. If "Up next" is empty, halt and tell the user "ROADMAP exhausted"
+
+**Skip task types that auto-mode shouldn't do:**
+- Tasks marked `HITL` (human-in-the-loop) — halt and ask
+- Tasks of type `spike` if their PRD is empty — halt and ask the user to provide direction first
+
+For the picked task:
+
+1. Determine the task ID (next sequential number, see `tasks/` for highest existing)
+2. Determine the task type (`feature` / `bug` / `refactor` / `chore` / `spike`) from the ROADMAP entry
+3. Create `tasks/NNN-<type>-<slug>/` directory
+4. Generate `PRD.md` using the template below — fill in based on ROADMAP entry, ARCHITECTURE.md context, and DONT.md constraints
+5. Generate `verify.sh` — a runnable shell script that exits 0 on success, non-zero on failure
+6. Update `STATE.md` `current_task` field to `NNN-<type>-<slug>`
+
+**PRD.md template:**
+
+```markdown
+# Task NNN — <title>
+
+**Type**: feature | bug | refactor | chore | spike
+**Created**: YYYY-MM-DD
+**Status**: in_progress
+
+## What
+
+One paragraph: end-to-end behavior, not layer-by-layer implementation.
+
+## Why
+
+One paragraph: motivation, link to ROADMAP entry or upstream issue.
+
+## Acceptance criteria
+
+- [ ] Criterion 1 (must be verifiable by verify.sh)
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Constraints
+
+Reference relevant lines from DONT.md and ARCHITECTURE.md. Be specific.
+
+## Implementation notes
+
+Brief sketch of approach. Avoid file paths that may go stale; reference modules/components by domain name.
+```
+
+**verify.sh template:**
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Task NNN verification
+# Each acceptance criterion above should map to a check below.
+
+echo "Running task NNN verification..."
+
+# Example: run tests for the new module
+# pytest tests/test_<module>.py -v
+
+# Example: lint
+# npm run lint
+
+# Example: smoke test the feature
+# ./run-feature.sh && grep "expected" output.log
+
+echo "✅ All checks passed"
+```
+
+After generating PRD + verify.sh: **print a one-line summary and proceed to Step 2 without asking for confirmation** (unless `--review` flag was passed).
+
+If `--review` flag was passed: print the PRD content and ask "Proceed with implementation? (yes/no)" before continuing.
+
+## Step 2 — Build
+
+Implement the task per the PRD at `tasks/<current_task>/PRD.md` (the path comes from STATE.md `current_task`).
+
+**Hard rules:**
+
+- Re-read `DONT.md` before touching any file. If a planned change violates DONT.md, halt and report.
+- Stay within the modules implied by the PRD. If the task requires changes outside the implied scope, halt and ask.
+- Keep edits minimal — match acceptance criteria, no gold-plating.
+- Use TaskCreate / TaskUpdate (the in-session task tracker) to track sub-steps within this task.
+
+**Stop conditions** (halt immediately and report):
+
+- Same test fails 3+ times after fix attempts
+- A required file/dependency is missing and you'd have to invent its design
+- DONT.md violation discovered mid-implementation
+- Number of files modified exceeds 10 (sanity check against runaway changes)
+
+## Step 3 — Verify
+
+Run the task verify script: `bash tasks/<current_task>/verify.sh`.
+
+Then run the project-level `./verify.sh` (regression defense). If it doesn't exist, skip this and note in the report.
+
+**If task verify fails**: do not retry blindly. Read the failure, fix the cause, re-run. Three failures in a row → halt and report.
+
+**If project verify fails**: halt immediately. Do not archive. This is a regression — surface it with full diagnostic detail.
+
+## Step 4 — Archive
+
+Only reached if both verifies pass.
+
+1. Generate `tasks/<current_task>/report.md` using the template below
+2. Generate `tasks/<current_task>/CHANGES.md` listing files added/modified/deleted with brief reason
+3. Update `tasks/<current_task>/PRD.md` — change `Status: in_progress` to `Status: done`
+4. Update `STATE.md`:
+   - `current_task` → `null`
+   - `last_completed` → this task ID with date
+   - `last_verify` → ✅ pass with timestamp
+   - Append a one-line entry to "Recent decisions" if a non-obvious choice was made
+5. Update `ROADMAP.md`:
+   - Move this task from "In progress" to "Done" (or mark `[x]`)
+
+**report.md template:**
+
+```markdown
+# Task NNN Verify Report
+
+**Task**: <type>-<slug>
+**Verified**: YYYY-MM-DD HH:MM
+**Status**: ✅ PASS
+**Duration**: <seconds>s (build) + <seconds>s (verify)
+
+## Acceptance criteria
+
+- [x] Criterion 1
+- [x] Criterion 2
+
+## Tests run
+
+- <test file or command> — <result>
+- Project verify.sh — passed (regression OK) | skipped (not present)
+
+## Files changed
+
+See CHANGES.md.
+
+## Notes
+
+Anything non-obvious worth flagging for future readers. Skip if nothing notable.
+```
+
+After archive: print one-line success summary and exit. Do **not** start the next task — that's `/auto`'s job.
+
+## Stop conditions summary
+
+Halt immediately, do not proceed silently, in any of these cases:
+
+| Condition | Action |
+|---|---|
+| Required state files missing | Tell user to run `/init-arch` |
+| ROADMAP exhausted | Report "all tasks done" |
+| Next task is `🛑 needs-review` or `HITL` | Report and ask |
+| DONT.md violation | Report and ask how to proceed |
+| Same test fails 3+ times | Report failure with diagnostics |
+| Files modified > 10 | Report and ask |
+| Project verify.sh fails after task verify passes | Report regression, do not archive |
+
+## When NOT to use this skill
+
+- Project skeleton not initialized → use `/init-arch` first
+- User wants to plan only without building → tell them this skill is one-shot; suggest manually editing ROADMAP if they want to think first
+- User wants continuous multi-task execution → use `/auto` instead
+
+</supporting-info>

package/skills/report/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: report
+description: Generate a project status report from STATE.md, ROADMAP.md, and the tasks/ archive. Use when the user wants a snapshot of progress — what's done, what's in flight, what's blocked, recent verify results — without re-reading every state file. Read-only.
+---
+
+<what-to-do>
+
+Produce a concise, accurate status report for the project.
+
+The user's intent: they want to understand current state at a glance. Maybe they're returning after time away, preparing a standup update, or sharing progress with a collaborator. They don't want to grep through every file themselves.
+
+This skill is **read-only**. It never modifies state, code, or docs.
+
+</what-to-do>
+
+<supporting-info>
+
+## Step 0 — Load inputs
+
+Read:
+1. `STATE.md`
+2. `ROADMAP.md`
+3. `ARCHITECTURE.md` (purpose line only — for the report header)
+4. List `tasks/` directory; for each subdir, read `report.md` if present (success records) or `PRD.md` (in-progress / failed)
+
+If state files missing → halt, tell user to run `/init-arch`.
+
+Parse optional flags:
+- `--last N` — show only the last N completed tasks (default: 5)
+- `--verbose` — include full acceptance criteria for each completed task
+- `--format markdown|plain` — output style (default: markdown)
+
+## Step 1 — Compute report sections
+
+### Header
+- Project purpose (first paragraph of ARCHITECTURE.md)
+- Report timestamp
+
+### Current focus
+- `current_task` from STATE.md — if set, include task title + acceptance criteria status
+- If `null`, say "no task in flight"
+
+### Recently completed (last N)
+- Pull from `tasks/*/report.md` sorted by verify timestamp descending
+- For each: ID, title, verify status, duration
+
+### Up next
+- First 5 entries from ROADMAP "Up next" section
+- Mark `🛑 needs-review` and `HITL` flags clearly
+
+### Blocked / needs human
+- Any ROADMAP entries with `🛑 needs-review` or `HITL`
+- `STATE.md` `blocked` field if not "none"
+
+### Recent decisions
+- Last 5 entries from STATE.md "Recent decisions"
+
+### Verify health
+- `STATE.md` `last_verify` field
+- Count of consecutive passing tasks (scan tasks/ in reverse, stop at first ❌)
+
+## Step 2 — Render
+
+Default markdown format:
+
+```markdown
+# Project Status — <project name>
+
+> <one-line purpose>
+>
+> Generated: <YYYY-MM-DD HH:MM>
+
+## Current focus
+
+**Task**: NNN-<type>-<slug>
+**Started**: <date>
+**Acceptance criteria**:
+- [x] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+(or "No task in flight — run `/plan-next` to start the next one.")
+
+## Recently completed (last 5)
+
+| ID | Title | Verified | Duration |
+|---|---|---|---|
+| 008-feature-foo | Add login flow | 2026-05-08 14:22 ✅ | 4m 12s |
+| 007-bug-bar | Fix timezone bug | 2026-05-08 11:05 ✅ | 1m 40s |
+
+## Up next
+
+- [ ] 009-feature-baz — Add password reset
+- [ ] 010-refactor-qux — Extract auth middleware (🛑 needs-review)
+- [ ] 011-feature-quux — Add 2FA (HITL)
+
+## Blocked / needs attention
+
+- 010-refactor-qux: needs-review marker — see ROADMAP for context
+- 011-feature-quux: HITL — requires human implementation
+
+## Recent decisions (last 5)
+
+- 2026-05-08: Switched session storage from JWT to server-side cookies
+- 2026-05-07: Adopted pytest-asyncio for async test cases
+- ...
+
+## Verify health
+
+- Last verify: ✅ pass (2026-05-08 14:22)
+- 8 consecutive passing tasks
+```
+
+Plain format: same content, no tables, no headers — flat text.
+
+## Behavioral rules
+
+- **Never modify any file.** This is observational only.
+- **Never invent data.** If a section has no content (e.g. no completed tasks yet), say so explicitly — don't fabricate.
+- Date formatting: ISO 8601 (YYYY-MM-DD HH:MM) for accuracy; relative time ("3 days ago") only as supplement, never replacement.
+- Don't editorialize. Report what's there, don't recommend next steps unless explicitly asked.
+
+## When NOT to use this skill
+
+- You want to fix something the report would surface → use `/plan-next` or `/sync-arch`.
+- You only need to know the next task → just read `STATE.md` `next_planned`.
+- Project not initialized → use `/init-arch`.
+
+</supporting-info>

package/skills/sync-arch/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: sync-arch
+description: Reconcile ARCHITECTURE.md / DONT.md / ROADMAP.md with the current code reality. Use when the codebase has drifted from the docs (after manual edits, after a long auto-mode run, or when `/plan-next` keeps producing `🛑 needs-review` markers). Surveys the code, proposes diffs, applies them only with user confirmation.
+---
+
+<what-to-do>
+
+Detect drift between the project state files and the actual codebase, then update the docs to match reality (or flag genuine architecture changes for human decision).
+
+The user's intent: their docs and code have fallen out of sync. They don't want to rewrite from scratch (`/init-arch` would do that and lose history); they want a targeted reconciliation that preserves intentional decisions while correcting stale facts.
+
+This skill **proposes** changes — it does not silently rewrite the architecture. The user approves each diff before it's applied.
+
+</what-to-do>
+
+<supporting-info>
+
+## Step 0 — Load current state
+
+Read in this order:
+1. `ARCHITECTURE.md`
+2. `DONT.md`
+3. `ROADMAP.md`
+4. `STATE.md`
+5. Most recent 3 entries under `tasks/` (to see what's recently been built)
+
+If any of the four state files is missing → halt, tell user to run `/init-arch`.
+
+Parse optional flags:
+- `--file <ARCHITECTURE|DONT|ROADMAP>` — only reconcile one file
+- `--apply` — apply all proposed diffs without per-file confirmation (use with care)
+
+## Step 1 — Survey the codebase
+
+Use the Explore agent or direct grep/find to gather current truth:
+
+- Top-level directories and their apparent purpose
+- Build / config files (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, etc.)
+- New modules added since `ARCHITECTURE.md` last mentioned them
+- Removed or renamed modules still referenced in docs
+- Tech stack additions (new deps in lockfiles)
+- New conventions (test patterns, file structure)
+
+Don't try to summarize the whole codebase — focus on **what changed since the docs were written**. Use `git log --since=<last_arch_update>` if available to scope the search.
+
+## Step 2 — Compute drift per file
+
+### `ARCHITECTURE.md` drift
+
+- Modules in docs but not in code → propose removal or mark as deprecated
+- Modules in code but not in docs → propose addition with one-line purpose
+- Tech stack mismatches → propose update
+- Conventions that no longer hold → propose removal
+
+### `DONT.md` drift
+
+DON'T entries are intentional — never auto-remove. Instead:
+- For each entry, check if the constraint is still grep-able / verifiable
+- If the constraint references a path that no longer exists → flag for user review (don't delete; the rule may have been violated)
+- If a new constraint pattern is detectable in code (e.g. a new `legacy/` dir was added) → propose adding it for user confirmation
+
+### `ROADMAP.md` drift
+
+- Tasks marked `[ ]` whose acceptance criteria appear satisfied in code → propose marking `[x]`
+- Tasks in "Done" that have no corresponding `tasks/` entry → flag (likely manually added)
+- "In progress" tasks where `STATE.md` `current_task` is `null` → propose moving back to "Up next" or to "Done"
+
+## Step 3 — Present the diff
+
+For each file with proposed changes, show a unified-diff-style preview:
+
+```
+─── ARCHITECTURE.md ───
+@@ Modules table @@
++ | logger | Structured JSON logging | Added 2026-04 |
+- | legacy_auth | Old auth shim | Removed |
+
+@@ Tech stack @@
+- - Storage: SQLite
++ - Storage: SQLite + Redis (caching layer added in tasks/012)
+```
+
+Then ask: `Apply these changes to ARCHITECTURE.md? (yes / edit / skip)`
+
+- **yes** → write the changes
+- **edit** → let the user provide a counter-proposal, then write
+- **skip** → leave the file untouched, move to the next
+
+## Step 4 — Update STATE.md
+
+After all approved diffs are applied:
+
+- Append a one-line entry to `STATE.md` "Recent decisions": `<date>: /sync-arch reconciliation — updated <files>`
+- Do not change `current_task`, `last_completed`, or `last_verify` — those are owned by `/plan-next`.
+
+## Step 5 — Final summary
+
+```
+ai-driven-skills /sync-arch summary
+─────────────────────────────────────
+ARCHITECTURE.md: 3 changes applied | 1 skipped
+DONT.md:         0 changes applied | 2 flagged for review
+ROADMAP.md:      5 changes applied
+
+Items flagged for your review:
+  - DONT.md line 7 references `legacy/` which no longer exists — was this rule satisfied or violated?
+  - ROADMAP "Done" entry "004-feature-foo" has no tasks/ directory — was this manually added?
+
+Next:
+  <suggested action>
+```
+
+## Behavioral rules
+
+- **Never silently delete from `DONT.md`.** Constraints are intentional; flag, don't remove.
+- **Never invent purpose for unfamiliar modules.** If a module's intent isn't clear from code or comments, mark it `<unknown — please describe>` for the user to fill in.
+- **Never modify `tasks/NNN-.../` archives.** Those are historical records.
+- Preserve user formatting and ordering where possible — only diff what's actually changed in meaning.
+
+## When NOT to use this skill
+
+- Project just initialized → docs are the source of truth, no drift yet.
+- You want to start fresh → use `/init-arch` (it will refuse to overwrite, so back up first).
+- A single `🛑 needs-review` marker → resolve it inline in ROADMAP, no need for full sync.
+
+</supporting-info>

package/skills/verify/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: verify
+description: Run verification on demand. Executes the current task's verify.sh, then the project-level verify.sh, and reports pass/fail with diagnostics. Use when the user wants to spot-check the codebase outside the normal `/plan-next` lifecycle — after manual edits, before a commit, or to investigate a regression.
+---
+
+<what-to-do>
+
+Run the project's verification scripts and report the outcome clearly.
+
+The user's intent: they want to know whether the code is currently in a green state. They might have edited files manually, returned to the project after time away, or be about to commit. Don't try to fix anything — just run, observe, and report. If the user wants a fix, that's a separate `/plan-next` invocation.
+
+</what-to-do>
+
+<supporting-info>
+
+## Step 0 — Locate verify scripts
+
+1. Read `STATE.md` to determine `current_task`.
+2. If `current_task` is set, the task verify path is `tasks/<current_task>/verify.sh`.
+3. Project verify path is `./verify.sh` at repo root.
+
+If neither exists → halt and tell the user to run `/init-arch`.
+
+Parse optional flags:
+- `--task-only` — skip project verify
+- `--project-only` — skip task verify
+- `--task <id>` — verify a specific task instead of `current_task`
+
+## Step 1 — Run task verify (if applicable)
+
+If a task verify exists and `--project-only` was not passed:
+
+1. Run `bash tasks/<task>/verify.sh`.
+2. Capture exit code, stdout, stderr.
+3. Print one-line result: `✅ task <id> verify passed` or `❌ task <id> verify FAILED (exit N)`.
+
+Do **not** retry. Do **not** attempt a fix. This skill reports — it does not repair.
+
+## Step 2 — Run project verify (if applicable)
+
+If `./verify.sh` exists and `--task-only` was not passed:
+
+1. Run `bash ./verify.sh`.
+2. Capture exit code, stdout, stderr.
+3. Print one-line result.
+
+If `./verify.sh` is missing → note "no project verify configured" (not a failure).
+
+## Step 3 — Report
+
+Print a structured report:
+
+```
+ai-driven-skills /verify report
+─────────────────────────────────────
+Task verify (NNN-<type>-<slug>): ✅ PASS | ❌ FAIL | ⏭ skipped
+Project verify:                  ✅ PASS | ❌ FAIL | ⏭ skipped
+
+Duration: Xs total
+
+<If any failure, include the last 30 lines of output here, verbatim>
+
+Next:
+  <if all pass> Verification clean. Safe to commit / continue.
+  <if task fails> See tasks/<id>/PRD.md for acceptance criteria. Run /plan-next to resume work on this task.
+  <if project fails> Regression detected. Investigate before continuing — likely caused by recent edits.
+```
+
+## Behavioral rules
+
+- **Never modify code or scripts to make a check pass.**
+- **Never re-run a failing check more than once** (a single retry is OK to rule out flakiness — call it out if you do).
+- If the verify script itself errors (syntax error, missing interpreter), report that as a script bug, not a verify failure.
+- Don't update `STATE.md` `last_verify` here — that field is owned by `/plan-next` (which verifies as part of the task lifecycle). Manual verify runs are observational and shouldn't poison the state of record.
+
+## When NOT to use this skill
+
+- You want to fix a failing test → use `/plan-next` (it will plan a bug task).
+- You want to add new tests → that's a feature task, use `/plan-next`.
+- Project not initialized → use `/init-arch`.
+
+</supporting-info>