class-ai-agent 1.2.3 → 1.3.0

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

@@ -0,0 +1,39 @@
+# Agent continuity
+
+Cross-tool handoff lives in **`.agent/SESSION.md`** (committed). Cursor, Claude Code, and Kiro agents share this file.
+
+## Session start
+
+1. If **`.agent/SESSION.md`** exists, read it **before** planning or editing code.
+2. When the user says **continue**, **resume**, or **pick up**, use **`.claude/commands/resume.md`**.
+3. Then read **`tasks/todo.md`** and linked **SPEC** paths from SESSION **Pointers**.
+
+**Do not** call `codegraph_context` with `query` / `limit` for session resume — that tool requires **`task`** and is for code symbols, not handoff state. For continuity, read `.agent/SESSION.md` (and `tasks/todo.md`); use `codegraph_context` only when you need structural code context for the work described in SESSION.
+
+## Session end and phase changes
+
+1. Update **`.agent/SESSION.md`** before ending a session or switching tools — use **`.claude/commands/handoff.md`** when possible.
+2. Keep **Done**, **In progress**, and **Next** accurate; do not leave stale **In progress** items.
+3. Sync **`tasks/todo.md`** checkboxes when tasks change.
+
+## Security (SESSION.md)
+
+**Never** store in `.agent/SESSION.md`:
+
+- API keys, passwords, tokens, credentials
+- PII or customer data
+
+Use issue links, commit SHAs, and file paths instead.
+
+## Workflow integration
+
+| Phase | SESSION `phase` value |
+|-------|------------------------|
+| Spec | `spec` |
+| Plan | `plan` |
+| Build | `build` |
+| Test | `test` |
+| Review | `review` |
+| Debug | `debug` |
+
+Set **Meta → Tool** to `cursor`, `claude`, or `kiro` as appropriate.

package/.claude/skills/agent-continuity/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: Agent Continuity
+description: Cross-tool session handoff and resume via .agent/SESSION.md
+---
+
+# Agent Continuity Skill
+
+## Purpose
+
+Keep **Cursor**, **Claude Code**, and **Kiro** aligned on the same in-flight work using committed **`.agent/SESSION.md`**.
+
+---
+
+## When to apply
+
+| Situation | Action |
+|-----------|--------|
+| New chat, same feature | **Resume** — read SESSION first |
+| End of session | **Handoff** — update SESSION |
+| Switch IDE/tool | **Handoff** then **Resume** in new tool |
+| Switch persona | Update Meta `persona`; handoff notes for next role |
+| Phase change (plan → build) | Update Meta `phase` |
+
+---
+
+## Handoff checklist
+
+- [ ] Meta: date, phase, tool, persona
+- [ ] Goal still accurate (one paragraph)
+- [ ] Done: bullets with paths/commits
+- [ ] In progress + blockers
+- [ ] Next: numbered for next agent
+- [ ] Decisions: non-obvious choices
+- [ ] Gotchas: failures, test commands, env
+- [ ] Pointers: spec, tasks, branch, key files
+- [ ] `tasks/todo.md` synced
+- [ ] No secrets or PII in SESSION
+
+---
+
+## Resume checklist
+
+- [ ] Read `.agent/SESSION.md`
+- [ ] Read `tasks/todo.md` if linked
+- [ ] Read SPEC if linked
+- [ ] `git status` vs SESSION expectations
+- [ ] Run sanity build/test if Gotchas say so
+- [ ] Post resumption summary to user
+- [ ] Execute first **Next** step via workflow command
+
+---
+
+## SESSION schema
+
+See **`.agent/SESSION.template.md`** for the canonical sections.
+
+---
+
+## Commands
+
+| Command | File |
+|---------|------|
+| `/handoff` | `.cursor/commands/handoff.md` (`.claude/`, `.kiro/`) |
+| `/resume` | `.cursor/commands/resume.md` |
+
+---
+
+## Optional history
+
+Copy SESSION to `.agent/history/YYYY-MM-DD-slug.md` at milestones; commit for audit trail.

package/.cursor/CURSOR.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-This project uses **Cursor** with the same structured workflows, specialized agent personas, and coding standards as the Claude-oriented **`.claude/`** tree. Cursor-specific files live under **`.cursor/`**.
+This project uses **Cursor** with the same structured workflows, specialized agent personas, and coding standards as **`.claude/`** and **`.kiro/`**. Cursor-specific files live under **`.cursor/`**.
 
 ---
 
@@ -30,6 +30,9 @@ Follow this workflow for feature development:
 | `commands/debug.md` | Systematic diagnosis |
 | `commands/simplify.md` | Reduce complexity, same behavior |
 | `commands/fix-issue.md` | Analyze and fix reported issues |
+| `commands/handoff.md` | End session — update `.agent/SESSION.md` for cross-tool continuity |
+| `commands/resume.md` | Start session — load `.agent/SESSION.md` and continue prior work |
+| `commands/publish-npm.md` | **Maintainers:** draft release notes, bump version, update README, publish to npm |
 
 **How to use:** Open the markdown file, copy the section you need, or **@ mention** the file in Chat/Composer so the model loads it.
 
@@ -56,6 +59,24 @@ Project rules are **`.cursor/rules/*.mdc`**. They use YAML frontmatter:
 | Stack, structure, APIs | `tech-stack`, `project-structure`, `api-conventions` |
 | Data & naming | `naming-conventions`, `database` |
 | Ops & quality | `security`, `monitoring`, `testing`, `git-workflow`, `system-design` |
+| Code intelligence | `codegraph` (MCP usage; see below) |
+
+---
+
+## Code intelligence (CodeGraph)
+
+This project includes **[CodeGraph](https://github.com/colbymchenry/codegraph)** for local, structural code search via MCP.
+
+| Item | Location |
+|------|----------|
+| MCP server config | `.cursor/mcp.json` |
+| Usage rules | `.cursor/rules/codegraph.mdc` |
+| Symbol index (generated) | `.codegraph/` (gitignored) |
+| Setup reference | `.cursor/references/codegraph.md` |
+
+After installing scaffolding, **reload the Cursor window** (or restart Cursor) so the CodeGraph MCP server connects. Use `codegraph_*` tools for structural questions (callers, callees, traces, impact); use grep/read for literal text in comments or strings.
+
+If the index is missing, run `npx @colbymchenry/codegraph init -i` in the project root.
 
 ---
 
@@ -82,6 +103,7 @@ Reusable playbooks: **`.cursor/skills/*/SKILL.md`** (and related `.md` files whe
 | `incremental-implementation` | Vertical slices |
 | `deploy` | Deployment pipeline |
 | `security-review` | Security audit |
+| `agent-continuity` | Cross-tool session handoff via `.agent/SESSION.md` |
 
 ---
 
@@ -95,18 +117,28 @@ Reusable playbooks: **`.cursor/skills/*/SKILL.md`** (and related `.md` files whe
 | `testing-patterns.md` | Test structure |
 | `performance-checklist.md` | Performance |
 | `accessibility-checklist.md` | WCAG-oriented checks |
+| `codegraph.md` | CodeGraph install and Claude Code setup |
+| `agent-continuity.md` | Session handoff and `/resume` / `/handoff` |
 
 ---
 
 ## Config parity
 
-**`.cursor/settings.json`** lists directories (mirrors `.claude/settings.json` for Claude Code). Cursor natively loads **`.cursor/rules/*.mdc`**; other paths are documentation for humans and for `@` includes.
+**`.cursor/settings.json`** lists directories (mirrors `.claude/settings.json` for Claude Code). Cursor natively loads **`.cursor/rules/*.mdc`** and **`.cursor/mcp.json`** for MCP servers; other paths are documentation for humans and for `@` includes.
+
+---
+
+## 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 (Cursor, Claude Code, Kiro). See **`.cursor/references/agent-continuity.md`** and **`.cursor/rules/agent-continuity.mdc`**.
 
 ---
 
 ## Agent behavior
 
 1. Follow the workflow and use the command prompts when starting a phase.
-2. Apply **`.cursor/rules/`**; treat **`security.mdc`** as non-negotiable.
-3. Prefer tests first and small, buildable changes.
-4. **@ mention** the right **`.cursor/agents/`** file when the task matches that role.
+2. If **`.agent/SESSION.md`** exists, read it before planning or coding; run **`/resume`** when continuing prior work.
+3. Apply **`.cursor/rules/`**; treat **`security.mdc`** as non-negotiable.
+4. Prefer tests first and small, buildable changes.
+5. **@ mention** the right **`.cursor/agents/`** file when the task matches that role.
+6. Update **`.agent/SESSION.md`** (or **`/handoff`**) before ending a session.

package/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/mcp.json

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "codegraph": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@colbymchenry/codegraph",
+        "serve",
+        "--mcp",
+        "--path",
+        "${workspaceFolder}"
+      ]
+    }
+  }
+}

package/.cursor/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.