class-ai-agent 1.2.3 → 1.3.0

package/.cursor/references/codegraph.md

@@ -0,0 +1,87 @@
+# CodeGraph reference
+
+[CodeGraph](https://github.com/colbymchenry/codegraph) is a local, tree-sitter–parsed knowledge graph exposed to agents via MCP. **class-ai-agent** installs Cursor and Kiro MCP wiring plus usage rules, and runs `codegraph init -i` after scaffolding.
+
+## Cursor (included with class-ai-agent)
+
+| Item | Path |
+|------|------|
+| MCP config | `.cursor/mcp.json` |
+| Usage rules | `.cursor/rules/codegraph.mdc` |
+| Index (generated) | `.codegraph/` (gitignored) |
+
+1. Reload the Cursor window after install so MCP connects.
+2. Confirm **CodeGraph** appears under MCP in Cursor settings.
+3. Use `codegraph_*` tools for structural questions; grep/read for literal text.
+
+**Manual index:** `npx @colbymchenry/codegraph init -i`
+
+**Skip auto-index on install:** `CODEGRAPH_SKIP_INIT=1 npx class-ai-agent`
+
+## Kiro (included with class-ai-agent)
+
+| Item | Path |
+|------|------|
+| MCP config | `.kiro/settings/mcp.json` |
+| Usage rules | `.kiro/steering/codegraph.md` |
+| Index (generated) | `.codegraph/` (gitignored) |
+
+1. Restart Kiro after install so MCP connects.
+2. Confirm **CodeGraph** under MCP in Kiro IDE or CLI settings.
+3. Use `codegraph_*` tools for structural questions.
+
+See `.kiro/references/codegraph.md` for full notes.
+
+## Claude Code
+
+Project scaffolding does **not** add Claude MCP config. Install CodeGraph globally for Claude Code:
+
+```bash
+npx @colbymchenry/codegraph
+# or: npm i -g @colbymchenry/codegraph
+codegraph install --target=claude --yes
+```
+
+Then in each project: `codegraph init -i` (or rely on class-ai-agent’s post-install init for the shared `.codegraph/` index).
+
+See the [CodeGraph README](https://github.com/colbymchenry/codegraph) for tools, troubleshooting, and benchmarks.
+
+## Requirements
+
+- **Node 20+** recommended for CodeGraph (class-ai-agent CLI itself supports Node 16.7+).
+- First index can take a minute on large repos; progress prints during `npx class-ai-agent` install.
+
+## Tool parameters
+
+| Tool | Pass | Not |
+|------|------|-----|
+| `codegraph_search` | `query`, optional `limit` | — |
+| `codegraph_context` | **`task`** (natural-language area), optional **`maxNodes`** | `query`, `limit` |
+
+Example — wrong (search-style args on context):
+
+```json
+{ "query": "auth flow", "limit": 15 }
+```
+
+→ `Error: task must be a non-empty string`
+
+Example — correct:
+
+```json
+{ "task": "how authentication flow works", "maxNodes": 15 }
+```
+
+**Session handoff** (`/resume`, `.agent/SESSION.md`) is not a CodeGraph call — read those files with the editor Read tool.
+
+## Troubleshooting
+
+| Issue | Action |
+|-------|--------|
+| `task must be a non-empty string` | Use `task` (not `query`) on `codegraph_context`; use `maxNodes` (not `limit`). For `/resume`, read `.agent/SESSION.md` instead. |
+| MCP “not initialized” | Run `npx @colbymchenry/codegraph init -i` in project root |
+| MCP not connecting | Reload Cursor; verify `.cursor/mcp.json`; test `npx @colbymchenry/codegraph serve --mcp` |
+| Stale symbols after edit | Wait ~2s for watcher sync, or check staleness banner in tool output |
+| Init failed during install | Run `npx @colbymchenry/codegraph init -i` manually |
+
+Upstream: [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph)

package/.cursor/rules/agent-continuity.mdc

@@ -0,0 +1,44 @@
+---
+description: "Agent session continuity — cross-tool handoff via .agent/SESSION.md"
+alwaysApply: true
+---
+
+# 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 **`.cursor/commands/resume.md`** (or equivalent in `.claude/` / `.kiro/`).
+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 **`.cursor/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/.cursor/rules/codegraph.mdc

@@ -0,0 +1,47 @@
+---
+description: CodeGraph MCP usage guide — when to use which tool
+alwaysApply: true
+---
+ 
+## CodeGraph
+
+This project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.
+
+### When to prefer codegraph over native search
+
+Use codegraph for **structural** questions — what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.
+
+| Question | Tool |
+|---|---|
+| "Where is X defined?" / "Find symbol named X" | `codegraph_search` |
+| "What calls function Y?" | `codegraph_callers` |
+| "What does Y call?" | `codegraph_callees` |
+| "How does X reach/become Y? / trace the flow from X to Y" | `codegraph_trace` (one call = the whole path, incl. callback/React/JSX dynamic hops) |
+| "What would break if I changed Z?" | `codegraph_impact` |
+| "Show me Y's signature / source / docstring" | `codegraph_node` |
+| "Give me focused context for a task/area" | `codegraph_context` |
+| "See several related symbols' source at once" | `codegraph_explore` |
+| "What files exist under path/" | `codegraph_files` |
+| "Is the index healthy?" | `codegraph_status` |
+
+### Tool parameters (do not mix)
+
+| Tool | Required arg | Optional cap | Wrong args → error |
+|------|--------------|--------------|-------------------|
+| `codegraph_search` | **`query`** (symbol name) | `limit` (default 10) | — |
+| `codegraph_context` | **`task`** (feature/bug description) | `maxNodes` (default 20) | `query` / `limit` → **`task must be a non-empty string`** |
+
+`codegraph_context` is for **code structure** around a task — not for loading **`.agent/SESSION.md`** or `/resume` handoff (use **Read** + `.cursor/commands/resume.md`).
+
+### Rules of thumb
+
+- **Answer directly — don't delegate exploration.** For "how does X work" / architecture questions, answer with 2-3 codegraph calls: `codegraph_context` first, then ONE `codegraph_explore` for the source of the symbols it surfaces. For a specific **flow** ("how does X reach Y") start with `codegraph_trace` from→to — one call returns the whole path with dynamic hops bridged — then ONE `codegraph_explore` for the bodies; don't rebuild the path with `codegraph_search` + `codegraph_callers`. Codegraph IS the pre-built index, so spawning a separate file-reading sub-task/agent — or running a grep + read loop — repeats work codegraph already did and costs more for the same answer.
+- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep — that's slower, less accurate, and wastes context.
+- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.
+- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context — `codegraph_context` is one call.
+- **Don't loop `codegraph_node` over many symbols** — one `codegraph_explore` call returns several symbols' source grouped in a single capped call, while each separate node/Read call re-reads the whole context and costs far more.
+- **Index lag — check the staleness banner, don't guess a wait.** When a codegraph response starts with "⚠️ Some files referenced below were edited since the last index sync…", the listed files are pending re-index — Read those specific files for accurate content. Files NOT in that banner are fresh and codegraph is authoritative for them. `codegraph_status` also lists pending files under "Pending sync".
+
+### If `.codegraph/` doesn't exist
+
+The MCP server returns "not initialized." Ask the user: *"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?"*

package/.cursor/rules/cursor-overview.mdc

@@ -18,18 +18,25 @@ Use the same phase order as in `.cursor/CURSOR.md`:
 5. **Review** — `.cursor/commands/review.md` (five-axis: `.cursor/skills/code-review/`)
 6. **Ship** — `.cursor/commands/deploy.md`
 
-Supporting prompts: `debug`, `simplify`, `fix-issue` in `.cursor/commands/`.
+Supporting prompts: `debug`, `simplify`, `fix-issue`, `handoff`, `resume` in `.cursor/commands/`. Maintainers: `publish-npm` (say **push to npm repo** to draft README release notes and publish).
+
+**Agent continuity:** committed **`.agent/SESSION.md`** — read at session start (`/resume`), update at end (`/handoff`). See **`.cursor/rules/agent-continuity.mdc`**.
 
 ## Mandatory standards
 
 - Follow **`.cursor/rules/`** (`.mdc`). **`security.mdc`** is always applied; other rule files apply when matching globs are in scope (see each file’s frontmatter).
 - Prefer **tests first** and **small vertical slices** (see `.cursor/skills/incremental-implementation/`).
 - Use **`.cursor/references/`** for checklists (security, testing, performance, accessibility).
+- For **structural** code questions (symbols, callers, callees, traces, impact), prefer **CodeGraph** MCP tools (`codegraph_*`) per **`.cursor/rules/codegraph.mdc`** instead of grep/read exploration loops.
 
 ## Agents (personas)
 
 Specialized instructions live in **`.cursor/agents/`**. In Cursor, **@ mention** the file you want (e.g. `@.cursor/agents/code-reviewer.md`) when you need that role.
 
-## Relation to `.claude/`
+## Relation to `.claude/` and `.kiro/`
+
+- **`.claude/`** — Claude Code
+- **`.cursor/`** — Cursor
+- **`.kiro/`** — Kiro (steering + MCP; sync from `.cursor/` via `npm run sync:kiro`)
 
-If both folders exist: **`.claude/`** targets Claude Code; **`.cursor/`** targets Cursor. Keep them aligned when you change workflows or standards.
+Keep all three aligned when you change workflows or standards.

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

@@ -0,0 +1,146 @@
+# Kiro AI agent configuration
+
+## Overview
+
+This project uses **Kiro** with the same structured workflows, specialized agent personas, and coding standards as **`.claude/`** and **`.cursor/`**. Kiro-specific files live under **`.kiro/`**.
+
+---
+
+## Development workflow
+
+Follow this workflow for feature development:
+
+```
+/spec  →  /plan  →  /build  →  /test  →  /review  →  Ship
+```
+
+| Phase | Prompt source | Purpose |
+|-------|----------------|--------|
+| **Define** | `.kiro/commands/spec.md` | PRD: objectives, scope, boundaries |
+| **Plan** | `.kiro/commands/plan.md` | Vertical slices, acceptance criteria |
+| **Build** | `.kiro/commands/build.md` | Incremental implementation, TDD |
+| **Verify** | `.kiro/commands/test.md` | Tests and verification |
+| **Review** | `.kiro/commands/review.md` | Five-axis review before merge |
+| **Ship** | `.kiro/commands/deploy.md` | Build, test, deploy |
+
+### Supporting prompts
+
+| File | Purpose |
+|------|---------|
+| `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 **#steering reference or paste from** the file in Chat/Composer so the model loads it.
+
+---
+
+## Core principles
+
+- **TDD** — Failing tests first, then implementation (`.kiro/skills/tdd/`)
+- **Incremental implementation** — Small vertical slices (`.kiro/skills/incremental-implementation/`)
+- **Five-axis review** — Correctness, readability, architecture, security, performance (`.kiro/skills/code-review/`)
+
+---
+
+## Mandatory standards (steering)
+
+Project standards are **`.kiro/steering/*.md`**. They use YAML frontmatter:
+
+- **`inclusion: always`** — Loaded every session (`kiro-overview.md`, `security.md`, `codegraph.md`, `agent-continuity.md`)
+- **`inclusion: fileMatch`** — Loaded when edited files match `fileMatchPattern`
+- **`inclusion: manual`** — Reference with `#filename` in chat or `/` slash commands
+
+| Topic | Rule file |
+|-------|-----------|
+| Clean code, style, errors | `clean-code`, `code-style`, `error-handling` |
+| 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) |
+| Agent continuity | `agent-continuity` (`.agent/SESSION.md` handoff) |
+
+---
+
+## 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 **`.kiro/references/agent-continuity.md`** and **`.kiro/steering/agent-continuity.md`**.
+
+---
+
+## Code intelligence (CodeGraph)
+
+This project includes **[CodeGraph](https://github.com/colbymchenry/codegraph)** for local, structural code search via MCP.
+
+| Item | Location |
+|------|----------|
+| MCP server config | `.kiro/settings/mcp.json` |
+| Usage rules | `.kiro/steering/codegraph.md` |
+| Symbol index (generated) | `.codegraph/` (gitignored) |
+| Setup reference | `.kiro/references/codegraph.md` |
+
+After installing scaffolding, **restart Kiro** 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.
+
+---
+
+## Agent personas
+
+Instructions live in **`.kiro/agents/`**. Invoke by **referencing** the file (e.g. `@.kiro/agents/backend.md`).
+
+| Area | File |
+|------|------|
+| Frontend, backend, architecture | `frontend.md`, `backend.md`, `systems-architect.md` |
+| Quality | `code-reviewer.md`, `test-engineer.md`, `qa.md`, `security-auditor.md` |
+| Product & content | `project-manager.md`, `ui-ux-designer.md`, `copywriter-seo.md` |
+
+---
+
+## Skills
+
+Reusable playbooks: **`.kiro/skills/*/SKILL.md`** (and related `.md` files where present).
+
+| Skill | Use for |
+|-------|---------|
+| `tdd` | Red–green–refactor |
+| `code-review` | Five-axis review |
+| `incremental-implementation` | Vertical slices |
+| `deploy` | Deployment pipeline |
+| `security-review` | Security audit |
+| `agent-continuity` | Cross-tool session handoff via `.agent/SESSION.md` |
+
+---
+
+## Reference checklists
+
+**`.kiro/references/`**
+
+| File | Use for |
+|------|---------|
+| `security-checklist.md` | Pre-deploy security |
+| `testing-patterns.md` | Test structure |
+| `performance-checklist.md` | Performance |
+| `accessibility-checklist.md` | WCAG-oriented checks |
+| `codegraph.md` | CodeGraph setup (Kiro, Cursor, Claude Code) |
+| `agent-continuity.md` | Session handoff and `/resume` / `/handoff` |
+
+---
+
+## Config parity
+
+**`.kiro/settings.json`** lists directories (mirrors `.cursor/settings.json`). Kiro loads **`.kiro/steering/*.md`**, root **`AGENTS.md`**, and **`.kiro/settings/mcp.json`**.
+
+---
+
+## Agent behavior
+
+1. Follow the workflow and use the command prompts when starting a phase.
+2. If **`.agent/SESSION.md`** exists, read it before planning or coding; run **`/resume`** when continuing prior work.
+3. Apply **`.kiro/steering/`**; treat **`security.md`** as non-negotiable.
+4. Prefer tests first and small, buildable changes.
+5. **#steering reference or paste from** the right **`.kiro/agents/`** file when the task matches that role.
+6. Update **`.agent/SESSION.md`** (or **`/handoff`**) before ending a session.