class-ai-agent 1.2.3 → 1.3.0

package/.agent/README.md

@@ -0,0 +1,33 @@
+# Agent continuity (`.agent/`)
+
+Committed handoff state so **Cursor**, **Claude Code**, and **Kiro** agents can continue the same work without re-discovering context.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| **`SESSION.md`** | Live handoff — read at session start, update at session end |
+| **`SESSION.template.md`** | Schema reference (do not edit for handoff; copy to `SESSION.md` on fresh install) |
+| **`history/`** | _(optional)_ milestone snapshots, e.g. `2025-06-02-feature-x.md` |
+
+## Workflow
+
+1. **Start** — Run `/resume` (or read `SESSION.md` first). Then `tasks/todo.md`, then linked `SPEC.md`.
+2. **Work** — Follow `.cursor/`, `.claude/`, or `.kiro/` workflow (`/build`, etc.).
+3. **End** — Run `/handoff` to refresh `SESSION.md` before closing the chat or switching tools.
+
+## What to put in `SESSION.md`
+
+- Goal, done / in progress / next steps
+- Decisions and gotchas the next agent must know
+- Pointers to spec, tasks, branch, key files
+
+## What NOT to put here
+
+- API keys, passwords, tokens, or credentials
+- PII or customer data
+- Long logs (link to issues or commits instead)
+
+## Commit to git
+
+`SESSION.md` is meant to be **committed** so the whole team and any IDE can resume. Keep it concise and current.

package/.agent/SESSION.md

@@ -0,0 +1,54 @@
+# Agent session
+
+> Cross-tool handoff state for Cursor, Claude Code, and Kiro. Update at session end (`/handoff`) or phase changes; read at session start (`/resume`).
+
+## Meta
+
+| Field | Value |
+|-------|-------|
+| **Updated** | 2026-06-02 |
+| **Phase** | build |
+| **Tool** | cursor |
+| **Persona** | _(maintainer)_ |
+
+## Goal
+
+Ship and document **class-ai-agent** scaffolding (Cursor / Claude / Kiro), **agent continuity** (`.agent/SESSION.md`, `/resume`, `/handoff`), and clear **CodeGraph** usage so agents do not confuse MCP parameters or use CodeGraph for session handoff.
+
+## Done
+
+- Diagnosed `Error: task must be a non-empty string` — wrong args on `codegraph_context` (`query`/`limit` vs `task`/`maxNodes`).
+- Documented parameter split in `.cursor/rules/codegraph.mdc`, `.cursor/references/codegraph.md`, `.claude/`, `.kiro/` (via `npm run sync:kiro`).
+- Clarified in agent-continuity rules: resume handoff = Read `SESSION.md`, not CodeGraph.
+
+## In progress
+
+- Uncommitted doc fixes (8 files) on `main`.
+- **Blockers:** none
+
+## Next
+
+1. Review and commit CodeGraph / agent-continuity doc changes (if approved).
+2. Optionally add `SESSION.md` to `.gitignore` exclusion note in README — **do commit** `SESSION.md` for this repo when it reflects real team state (template stays in package).
+3. Run `npm run test:cli` before any npm publish.
+4. Run `/handoff` after each meaningful session end.
+
+## Decisions
+
+- Session resume uses **`.agent/SESSION.md` + `/resume`**, not `codegraph_context`.
+- `codegraph_context` requires **`task`**; `codegraph_search` requires **`query`**.
+
+## Gotchas
+
+- Calling `codegraph_context` with `{ "query": "...", "limit": 15 }` → `task must be a non-empty string`.
+- CodeGraph MCP may need `projectPath` if workspace root is not detected.
+- Verify CLI: `npm run test:cli`
+
+## Pointers
+
+| Item | Location |
+|------|----------|
+| Spec | _(none — package maintenance)_ |
+| Tasks | _(no `tasks/todo.md` yet)_ |
+| Branch | `main` |
+| Key files | `.cursor/commands/resume.md`, `.cursor/commands/handoff.md`, `.cursor/rules/agent-continuity.mdc`, `.cursor/rules/codegraph.mdc`, `bin/class-ai-agent.cjs` |

package/.agent/SESSION.template.md

@@ -0,0 +1,46 @@
+# Agent session
+
+> Cross-tool handoff state for Cursor, Claude Code, and Kiro. Update at session end (`/handoff`) or phase changes; read at session start (`/resume`).
+
+## Meta
+
+| Field | Value |
+|-------|-------|
+| **Updated** | YYYY-MM-DD |
+| **Phase** | spec \| plan \| build \| test \| review \| debug |
+| **Tool** | cursor \| claude \| kiro |
+| **Persona** | _(optional, e.g. backend, architect)_ |
+
+## Goal
+
+_One paragraph: what we are building and why._
+
+## Done
+
+- _(completed work; include file paths or PR refs when useful)_
+
+## In progress
+
+- _(current task)_
+- **Blockers:** _(none \| describe)_
+
+## Next
+
+1. _(ordered steps for the next agent)_
+
+## Decisions
+
+- _(non-obvious choices: API shape, libraries, approach)_
+
+## Gotchas
+
+- _(failed attempts, env quirks, test commands that matter)_
+
+## Pointers
+
+| Item | Location |
+|------|----------|
+| Spec | `SPEC.md` or `docs/specs/...` |
+| Tasks | `tasks/todo.md` |
+| Branch | `feature/...` |
+| Key files | _(paths)_ |

package/.claude/CLAUDE.md

@@ -36,6 +36,15 @@ Follow this workflow for all feature development:
 | `/debug` | Systematic error diagnosis and root cause analysis |
 | `/simplify` | Reduce complexity without changing behavior |
 | `/fix-issue` | Analyze and fix reported issues |
+| `/handoff` | End session — update `.agent/SESSION.md` for cross-tool continuity |
+| `/resume` | Start session — load `.agent/SESSION.md` and continue prior work |
+| `publish-npm` | **Maintainers:** draft release notes, bump version, update README, publish to npm |
+
+---
+
+## Agent continuity
+
+Cross-tool handoff lives in **`.agent/SESSION.md`** (committed). Use **`/resume`** at session start and **`/handoff`** at session end when switching chats or tools. See **`.claude/references/agent-continuity.md`** and **`.claude/rules/agent-continuity.md`**.
 
 ---
 
@@ -86,6 +95,7 @@ All rules in `.claude/rules/` are **mandatory** and must be followed:
 | `monitoring.md` | Prometheus, Grafana, logging, alerting |
 | `testing.md` | Coverage thresholds, test patterns |
 | `git-workflow.md` | Branching strategy, conventional commits |
+| `agent-continuity.md` | Session handoff via `.agent/SESSION.md` |
 
 ---
 
@@ -128,6 +138,7 @@ Specialized skills for complex operations:
 | `incremental-implementation` | Vertical slice development |
 | `deploy` | Full deployment pipeline |
 | `security-review` | Security audit checklist |
+| `agent-continuity` | Cross-tool session handoff via `.agent/SESSION.md` |
 
 ---
 
@@ -141,15 +152,19 @@ Quick references in `.claude/references/`:
 | `testing-patterns.md` | Test structure and anti-patterns |
 | `performance-checklist.md` | Core Web Vitals, optimization |
 | `accessibility-checklist.md` | WCAG 2.1 AA compliance |
+| `codegraph.md` | CodeGraph install (Claude Code) and Cursor MCP notes |
+| `agent-continuity.md` | Session handoff and `/resume` / `/handoff` |
 
 ---
 
 ## Agent Behavior Guidelines
 
 1. **Follow the workflow** — Use `/spec` → `/plan` → `/build` → `/review`
-2. **Apply mandatory rules** — All rules in `.claude/rules/` are non-negotiable
-3. **Test first** — Write failing tests before implementing
-4. **Incremental changes** — Small commits, always buildable
-5. **Explain before acting** — Describe changes before making them
-6. **Fix root causes** — Don't patch symptoms
-7. **Use the right agent** — Invoke specialized agents for their domains
+2. **Read `.agent/SESSION.md`** before planning or coding when present; use **`/resume`** to continue prior work
+3. **Apply mandatory rules** — All rules in `.claude/rules/` are non-negotiable
+4. **Test first** — Write failing tests before implementing
+5. **Incremental changes** — Small commits, always buildable
+6. **Explain before acting** — Describe changes before making them
+7. **Fix root causes** — Don't patch symptoms
+8. **Use the right agent** — Invoke specialized agents for their domains
+9. **Hand off** — Update `.agent/SESSION.md` with **`/handoff`** before ending a session

package/.claude/commands/build.md

@@ -23,9 +23,10 @@ Implement tasks one at a time using Test-Driven Development. Each increment leav
 #### Step 1: Load Context
 
 ```
-1. Read the task's acceptance criteria
-2. Identify relevant existing code and patterns
-3. Understand types and interfaces involved
+1. Read `.agent/SESSION.md` if present (or run `/resume` at session start)
+2. Read the task's acceptance criteria from `tasks/todo.md`
+3. Identify relevant existing code and patterns
+4. Understand types and interfaces involved
 ```
 
 #### Step 2: RED — Write Failing Test
@@ -86,7 +87,7 @@ git commit -m "feat(tasks): add createTask function"
 
 #### Step 6: Mark Complete
 
-Update `tasks/todo.md`:
+Update `tasks/todo.md` and `.agent/SESSION.md` (**Done**, **In progress**, **Next**):
 ```markdown
 - [x] Task 1.1: Create task endpoint
 ```

package/.claude/commands/debug.md

@@ -20,7 +20,7 @@ When unexpected failures occur:
 3. **DIAGNOSE** — Follow the 6-step triage process
 4. **FIX** — Address root cause, not symptoms
 5. **GUARD** — Add tests to prevent recurrence
-6. **RESUME** — Only continue after verification
+6. **RESUME** — Only continue after verification; update `.agent/SESSION.md` with root cause, guard tests, and **Next**
 
 ---
 
@@ -236,6 +236,7 @@ git bisect reset                  # When done
 - Regression test added
 - All tests passing
 - Clear commit message explaining the fix
+- **`.agent/SESSION.md`** updated (Gotchas, Decisions, **Next**)
 
 ## Next Step
 

package/.claude/commands/handoff.md

@@ -0,0 +1,94 @@
+---
+name: handoff
+description: End-of-session — update .agent/SESSION.md for the next agent or tool
+---
+
+# /handoff — Session handoff
+
+> "Leave the next agent a map, not a maze."
+
+## Purpose
+
+Capture current work in **`.agent/SESSION.md`** so another chat, persona, or tool (Cursor, Claude Code, Kiro) can continue without re-discovering context.
+
+## When to use
+
+- End of a work session (before closing chat)
+- Switching tools (Cursor → Claude Code → Kiro)
+- Switching persona (e.g. architect → backend)
+- After completing a workflow phase (spec, plan, build, test, review)
+- Before opening a PR (document what reviewers should know)
+
+## Prerequisites
+
+- `.agent/SESSION.md` exists (created by `npx class-ai-agent` or copy from `.agent/SESSION.template.md`)
+- You have context on what was done this session
+
+## Workflow
+
+### Phase 1: Gather state
+
+1. **Review git** — branch name, uncommitted files, last commits
+2. **Review tasks** — open `tasks/todo.md`; sync checkboxes with reality
+3. **Review spec** — note linked `SPEC.md` or `docs/specs/...` path
+4. **Scan decisions** — what did we choose that is not obvious from code alone?
+5. **Scan gotchas** — what failed, env quirks, commands that matter
+
+### Phase 2: Update `.agent/SESSION.md`
+
+Refresh every section (use `.agent/SESSION.template.md` as schema):
+
+| Section | Content |
+|---------|---------|
+| **Meta** | `Updated` (today), `Phase`, `Tool` (cursor/claude/kiro), optional `Persona` |
+| **Goal** | One paragraph — still accurate? |
+| **Done** | Bullets with file paths or commit refs |
+| **In progress** | Current task; **Blockers** (none or describe) |
+| **Next** | Numbered steps for the *next* agent |
+| **Decisions** | Non-obvious choices made this session |
+| **Gotchas** | Failed attempts, test commands, env notes |
+| **Pointers** | Spec path, `tasks/todo.md`, branch, key files |
+
+### Phase 3: Sync `tasks/todo.md`
+
+- Mark completed items `[x]`
+- Add new tasks discovered during work
+- Remove or defer items that are out of scope
+
+### Phase 4: Risk note (if applicable)
+
+If work is **not** safe to pick up blindly, add under **Gotchas** or **In progress**:
+
+- Uncommitted changes and why
+- Failing tests or broken build
+- External blockers (API, review, dependency)
+
+### Phase 5: Optional milestone archive
+
+For major milestones, copy `SESSION.md` to:
+
+```
+.agent/history/YYYY-MM-DD-short-slug.md
+```
+
+Commit both `SESSION.md` and the history file when ready.
+
+## Security
+
+**Never** write to `SESSION.md`:
+
+- API keys, passwords, tokens, credentials
+- PII or customer data
+- Full stack traces with secrets
+
+Use issue links or commit SHAs instead.
+
+## Output
+
+- Updated **`.agent/SESSION.md`**
+- Updated **`tasks/todo.md`** (if it exists)
+- Short summary for the user: phase, next steps, blockers
+
+## Next step
+
+Tell the user to run **`/resume`** in the next session or tool, or commit and share the branch.

package/.claude/commands/plan.md

@@ -100,6 +100,7 @@ Save to `tasks/` directory:
 
 - `tasks/plan.md` — Full planning document with context
 - `tasks/todo.md` — Actionable task checklist
+- **`.agent/SESSION.md`** — Update Meta `phase` to `build`, **Pointers** → `tasks/todo.md` and spec path, **Next** → first `/build` task
 
 ```markdown
 # TODO: [Feature Name]

package/.claude/commands/publish-npm.md

@@ -0,0 +1,119 @@
+# Publish to npm (maintainers)
+
+## Description
+
+Publish **`class-ai-agent`** to the npm registry: draft release notes from git, get maintainer approval, update README, bump version, verify CLI, publish.
+
+## Triggers
+
+Use when the maintainer says any of:
+
+- **push to npm repo**
+- **publish to npm**
+- **publish class-ai-agent**
+
+Or **@ mention this file** in Chat/Composer (`.cursor/commands/publish-npm.md` in Cursor; `.kiro/commands/publish-npm.md` in Kiro).
+
+## Prerequisites
+
+- Changes are ready to ship; working tree reflects what you are publishing.
+- **`npm login`** completed for the `class-ai-agent` package scope.
+- Two-factor auth enabled for npm **writes** if the account requires it (see README *Publishing to npm*).
+
+## Workflow
+
+### 1. Resolve baseline version
+
+```bash
+git tag -l 'v*' --sort=-v:refname | head -1
+```
+
+If no `v*` tags exist, use the latest `### x.y.z` heading under **## Release notes** in README, or `package.json` version as the last shipped baseline.
+
+Strip a leading `v` from tags when comparing to semver (e.g. `v1.2.4` → `1.2.4`).
+
+### 2. Draft release notes (do not publish yet)
+
+```bash
+git log <lastTagOrBaseline>..HEAD --pretty=format:'- %s (%h)'
+```
+
+- Group related commits; rewrite subjects for user-facing clarity.
+- Drop noise (merge commits, duplicate WIP messages) unless relevant.
+- Present the bullet list to the maintainer and **wait for explicit approval or edits**.
+
+### 3. Confirm version bump
+
+Default: **`patch`** (`npm version patch --no-git-tag-version`).
+
+Use **`minor`** or **`major`** only if the maintainer requests it.
+
+### 4. Bump version
+
+```bash
+npm version patch --no-git-tag-version   # or minor | major
+```
+
+Read the new version from `package.json`.
+
+### 5. Update README
+
+Prefer the helper script after approval (write bullets to a temp file):
+
+```bash
+npm run release:readme -- --version NEW_VERSION --date YYYY-MM-DD --notes-file /path/to/notes.md
+```
+
+`notes.md` should contain one bullet per line (with or without leading `- `).
+
+If **## Release notes** is missing, add it before **## Contributing** first, then run the script.
+
+Fallback: manually insert at the top of **## Release notes**:
+
+```markdown
+### NEW_VERSION — YYYY-MM-DD
+
+- …
+```
+
+And sync the version badge: `version-NEW_VERSION` in the shields.io img (line ~21).
+
+### 6. Verify CLI
+
+```bash
+npm run test:cli
+```
+
+Stop on failure; do not publish.
+
+### 7. Publish
+
+```bash
+npm publish --access public
+```
+
+If npm prompts for **OTP**, the maintainer enters it in the terminal.
+
+On **403 / cannot publish over previously published versions**: bump with `npm version patch --no-git-tag-version` and retry (each semver can only be published once).
+
+### 8. Report
+
+Tell the maintainer:
+
+- Published version (from `package.json`)
+- https://www.npmjs.com/package/class-ai-agent
+
+**Do not** `git commit`, tag, or push unless the maintainer separately asks.
+
+## Maintainer quick reference
+
+| Step | Command / action |
+|------|------------------|
+| Draft | `git log <tag>..HEAD --pretty=format:'- %s (%h)'` |
+| Approve | Maintainer edits bullets in chat |
+| Bump | `npm version patch --no-git-tag-version` |
+| README | `npm run release:readme -- --version … --notes-file …` |
+| Test | `npm run test:cli` |
+| Publish | `npm publish --access public` |
+
+See also [README — Publishing to npm](../../README.md#publishing-to-npm-maintainers) and [README — Release notes](../../README.md#release-notes).

package/.claude/commands/resume.md

@@ -0,0 +1,107 @@
+---
+name: resume
+description: Start-of-session — load .agent/SESSION.md and continue prior work
+---
+
+# /resume — Continue prior work
+
+> "Read the map before you move."
+
+## Purpose
+
+Load cross-tool handoff state and continue work from a previous agent session without re-discovering context.
+
+## When to use
+
+- Starting a new chat on the same feature
+- Switching tools (Cursor ↔ Claude Code ↔ Kiro)
+- User says "continue", "pick up where we left off", or "resume"
+- After pulling a branch that includes an updated `.agent/SESSION.md`
+
+## Prerequisites
+
+- **`.agent/SESSION.md`** exists in the project root
+- If missing: run `npx class-ai-agent` or copy `.agent/SESSION.template.md` → `.agent/SESSION.md`
+
+## Workflow
+
+### Phase 1: Load handoff (read-only first)
+
+Read in this order:
+
+1. **`.agent/SESSION.md`** — goal, done, in progress, next, decisions, gotchas, pointers
+2. **`tasks/todo.md`** — if referenced in Pointers
+3. **`SPEC.md`** or path from Pointers — if in spec/plan/build phase
+
+> Do **not** edit code until Phase 3 plan is stated to the user.
+
+### Phase 2: Sanity check
+
+From SESSION **Gotchas** and **Pointers**, run quick checks when noted:
+
+- `git status` — uncommitted work matches SESSION?
+- Build/test commands listed in Gotchas — run if stale or uncertain
+- Branch matches Pointers
+
+If SESSION reports **blockers** or broken build, surface them before implementing.
+
+### Phase 3: State plan to user
+
+Reply with a short structured summary:
+
+```markdown
+## Resuming
+
+**Goal:** [from SESSION]
+**Phase:** [spec | plan | build | test | review | debug]
+**Last updated:** [Meta date] via [tool/persona]
+
+### Already done
+- ...
+
+### In progress
+- ...
+
+### Next (this session)
+1. ...
+
+### Risks / blockers
+- ...
+```
+
+Ask for confirmation only if SESSION is ambiguous or blockers need a decision.
+
+### Phase 4: Continue workflow
+
+| Phase in SESSION | Command to follow |
+|------------------|-------------------|
+| spec | `/spec` (refine) or `/plan` if spec is done |
+| plan | `/plan` or `/build` if plan exists |
+| build | `/build` |
+| test | `/test` |
+| review | `/review` |
+| debug | `/debug` |
+
+Update **Meta** in `.agent/SESSION.md` when you change phase or tool.
+
+### Phase 5: During work
+
+- After meaningful progress, update SESSION **Done** / **In progress** / **Next**
+- End session with **`/handoff`**
+
+## If SESSION is empty or stale
+
+1. Survey repo: `git log`, `tasks/todo.md`, open PRs
+2. Rebuild SESSION from evidence
+3. Ask user to confirm goal and next steps
+4. Run `/handoff` when aligned
+
+## Output
+
+- Resumption summary (Phase 3)
+- Explicit next action (first item from **Next**)
+- No code changes until plan is stated (unless user asked for a specific fix)
+
+## Next step
+
+Execute the first **Next** item using the appropriate workflow command (`/build`, etc.).

package/.claude/commands/spec.md

@@ -89,7 +89,8 @@ After discovery, produce `SPEC.md` with these sections:
 
 - `SPEC.md` — The specification document
 - Clear alignment on what to build
+- **`.agent/SESSION.md`** — Initialize or update: set Meta `phase` to `plan`, **Goal**, **Pointers** → spec path, **Next** → run `/plan`
 
 ## Next Step
 
-After spec is approved, run `/plan` to decompose into tasks.
+After spec is approved, run `/plan` to decompose into tasks. Run `/handoff` if ending the session before planning.

package/.claude/references/agent-continuity.md

@@ -0,0 +1,42 @@
+# Agent continuity — quick reference
+
+## Files
+
+| Path | Role |
+|------|------|
+| `.agent/SESSION.md` | Live handoff (commit to git) |
+| `.agent/SESSION.template.md` | Schema reference |
+| `.agent/README.md` | Human overview |
+| `tasks/todo.md` | Task checklist (workflow) |
+| `SPEC.md` | Feature spec (workflow) |
+
+## Commands
+
+| Command | When |
+|---------|------|
+| **`/resume`** | Start of session — read SESSION, summarize, continue |
+| **`/handoff`** | End of session — write SESSION, sync tasks |
+
+## Read order (resume)
+
+1. `.agent/SESSION.md`
+2. `tasks/todo.md`
+3. Linked spec from SESSION Pointers
+
+## Install
+
+```bash
+npx class-ai-agent
+```
+
+Creates `.agent/` and seeds `SESSION.md` from template.
+
+## Rules
+
+- **Cursor:** `.cursor/rules/agent-continuity.mdc` (`alwaysApply`)
+- **Claude:** `.claude/rules/agent-continuity.md`
+- **Kiro:** `.kiro/steering/agent-continuity.md` (`inclusion: always`)
+
+## Skill
+
+`.cursor/skills/agent-continuity/SKILL.md` — full handoff/resume checklists.

package/.claude/references/codegraph.md

@@ -0,0 +1,50 @@
+# CodeGraph reference
+
+[CodeGraph](https://github.com/colbymchenry/codegraph) is a local, tree-sitter–parsed knowledge graph exposed to agents via MCP.
+
+## Claude Code setup
+
+**class-ai-agent** does not write Claude MCP config. Install CodeGraph for Claude Code globally:
+
+```bash
+npx @colbymchenry/codegraph
+# or: npm i -g @colbymchenry/codegraph
+codegraph install --target=claude --yes
+```
+
+In each project, build the index:
+
+```bash
+codegraph init -i
+```
+
+If you used **class-ai-agent** to scaffold the project, it may have already run `init -i` and created `.codegraph/` (shared by any agent that uses the index).
+
+## Cursor (via class-ai-agent)
+
+- `.cursor/mcp.json` — CodeGraph MCP server
+- `.cursor/rules/codegraph.mdc` — when to use `codegraph_*` tools
+
+Reload Cursor after install. See `.cursor/references/codegraph.md`.
+
+## Kiro (via class-ai-agent)
+
+- `.kiro/settings/mcp.json` — CodeGraph MCP server
+- `.kiro/steering/codegraph.md` — when to use `codegraph_*` tools
+
+Restart Kiro after install. See `.kiro/references/codegraph.md`.
+
+Or install globally: `codegraph install --target=kiro --yes`
+
+## Requirements
+
+- **Node 20+** recommended for CodeGraph.
+- Index data lives in `.codegraph/` — add to `.gitignore` (class-ai-agent does this automatically).
+
+## Troubleshooting
+
+| Issue | Action |
+|-------|--------|
+| `task must be a non-empty string` | On `codegraph_context`, use **`task`** (not `query`) and **`maxNodes`** (not `limit`). For `/resume`, read `.agent/SESSION.md` — not CodeGraph. |
+
+See [CodeGraph README — Troubleshooting](https://github.com/colbymchenry/codegraph#troubleshooting) or `.cursor/references/codegraph.md` for MCP setup.