thachvd-kit 1.0.29 → 1.0.31

package/README.md

@@ -1,194 +1,99 @@
 # thachvd-kit
 
-`thachvd-kit` bootstraps shared project rules for AI coding agents.
+`thachvd-kit` bootstraps project context for AI coding agents. It creates shared entry files and scan-based documentation so an agent can understand the repository quickly.
 
-It creates a compact cross-agent entry setup for Codex, Antigravity, and Claude Code, then stores scan-based project knowledge under `.agent/docs/` so the root instruction files stay small.
+Workflow skills are intentionally not copied into projects. Install [Superpowers](https://github.com/obra/superpowers#installation) through the official plugin surface for the AI client each member uses.
 
 ## Quick Start
 
-Install globally:
-
 ```bash
 npm install -g thachvd-kit
+cd your-project
+thachvd-kit init
+thachvd-kit setup
+thachvd-kit doctor
 ```
 
-Run inside a project:
-
-```bash
-thachvd-kit
-```
-
-By default, `thachvd-kit` scans the current project, generates shared AI-agent files, installs/configures Codegraph when needed, and configures Context7, Codegraph, and Playwright MCP for local AI clients. Use `--no-setup-mcp` to skip machine-level MCP setup.
+`init` is safe and project-focused. It does not install external tools, modify global AI skill folders, or create a second workflow engine.
 
-## What `init` Generates
+## Generated Files
 
-- `AGENTS.md`: shared entry instructions for Codex, Antigravity, Claude Code, and Cursor.
-- `CLAUDE.md`: Claude Code entry file that imports `AGENTS.md`.
-- `GEMINI.md`: Antigravity entry file that points to `AGENTS.md`.
-- `.cursorrules`: Cursor entry file that points to `AGENTS.md`.
-- `.agent/docs/project.md`: stack, commands, routing, and scan evidence.
-- `.agent/docs/architecture.md`: architecture map and maintenance rule.
+- `AGENTS.md`: shared project instructions.
+- `CLAUDE.md`: Claude Code entry file importing `AGENTS.md`.
+- `GEMINI.md`: Antigravity entry file.
+- `.cursorrules`: Cursor entry file.
+- `.agent/docs/project.md`: detected stack, commands, and project evidence.
+- `.agent/docs/architecture.md`: architecture notes to refine over time.
 - `.agent/docs/conventions.md`: coding and verification conventions.
-- `.agent/docs/workflow.md`: repeatable task flow for future AI work.
-- `.agent/docs/tooling.md`: setup hints for Playwright, codegraph, and native Codex/Claude skill folders.
-- `.agent/agents`, `.agent/skills`, `.agent/workflows`, `.agent/rules`.
-- `~/.codex/skills/`: selected Codex skills copied to the global user dir.
-- `.claude/skills`: selected Claude Code project skills copied from the kit.
-
-## Why Docs Live Under `.agent/docs`
-
-Root instruction files are loaded often, so they should stay short and stable. Project-specific details belong in `.agent/docs/`:
-
-- update `project.md` when stack, scripts, or tooling changes;
-- update `architecture.md` when structure or boundaries change;
-- update `conventions.md` when repeated patterns become clear;
-- update `workflow.md` when the repo needs special task steps.
-
-`AGENTS.md` tells every AI agent to read these docs before coding. If a doc contains `TODO: refine`, the agent should scan the repository and update the doc before product code changes.
+- `.agent/docs/workflow.md`: the project workflow contract.
+- `.agent/docs/tooling.md`: Superpowers, MCP, RTK, and Playwright setup.
+- `.agent/docs/getting-started.md`: member onboarding guide.
+- `.agent/docs/index-project-prompt.md`: durable prompt for the first project scan.
 
-## Platform Notes
+The kit does not generate `.agent/skills`, `.agent/workflows`, `.agent/agents`, Forge commands, Claude hooks, or client-specific skill copies.
 
-- Codex reads `AGENTS.md`.
-- Claude Code reads `CLAUDE.md`; this kit uses `@AGENTS.md` inside `CLAUDE.md` so Claude shares the same rules.
-- Antigravity can use `GEMINI.md`; this kit points it back to the shared `AGENTS.md`.
-- `.agent/skills` is committed shared knowledge. `thachvd-kit` also copies selected native skills into `~/.codex/skills/` for Codex and `.claude/skills` for Claude Code.
+## Workflow
 
-## Skill Usage Best Practice
+Superpowers is the primary workflow backend:
 
-Skills work best through progressive disclosure: the agent should first see skill names and descriptions, then read only the matching `SKILL.md` body.
+1. `brainstorming` for unclear requirements.
+2. `using-git-worktrees` for isolated work.
+3. `writing-plans`, then explicit approval.
+4. `test-driven-development` and `executing-plans` or `subagent-driven-development`.
+5. `requesting-code-review` and `verification-before-completion`.
+6. `finishing-a-development-branch`.
 
-- Keep `.agent/skills` as the complete shared source from the kit.
-- Let `thachvd-kit` copy selected skills to `~/.codex/skills/` for Codex and `.claude/skills` for Claude Code.
-- Make every `SKILL.md` frontmatter `description` specific: include when to use it, trigger phrases, and boundaries.
-- Run `thachvd-kit --help` to see a compact workflow guide. Forge commands appear after `init` and a client restart.
-- Use explicit prompts when implicit matching misses, for example `Use $webapp-testing to verify this UI` or `Use $clean-code before refactoring`.
-- Restart Codex or Claude Code if a newly copied or edited skill does not appear.
+For bugs, use `systematic-debugging`: reproduce, inspect, test hypotheses, add regression protection, fix the root cause, and verify.
 
-## Development Workflow
+For a trivial one-file change with no behavior or contract change, use the client's fast path. State the narrow scope and verification before editing. If the scope grows, return to brainstorming and planning.
 
-After install, Forge is the member-facing command suite. It accepts free-form text after the command, routes the request, and continues the selected workflow in the same turn. Questions remain normal chat; edit requests without a command are implicitly routed as `forge-task`.
+## Integrations
 
-### Client Commands
+### Superpowers
 
-| Client | Task | Fast path | Bug flow | Research | Review | Release |
-|---|---|---|---|---|---|
-| Codex | `$forge-task` | `$forge-fast` | `$forge-debug` | `$forge-research` | `$forge-review` | `$forge-release` |
-| Antigravity | `/forge-task` | `/forge-fast` | `/forge-debug` | `/forge-research` | `/forge-review` | `/forge-release` |
-| Claude Code | `/forge-task` | `/forge-fast` | `/forge-debug` | `/forge-research` | `/forge-review` | `/forge-release` |
-| Cursor | `/forge-task` | `/forge-fast` | `/forge-debug` | `/forge-research` | `/forge-review` | `/forge-release` |
+Install it separately for each AI client. The official guide contains the current commands for Claude Code, Antigravity, Codex App, Codex CLI, and Cursor.
 
-`init` installs these from `commands/`: Codex skills in `~/.codex/skills/forge-*`, Antigravity workflows in `.agent/workflows/forge-*`, Claude Code commands in `.claude/commands/forge-*`, and Cursor commands in `.cursor/commands/forge-*`. Restart or reload the client after installation.
+### codebase-memory-mcp
 
-| Situation | Command | Required flow |
-|---|---|---|
-| Question or analysis | direct answer | no edits |
-| One obvious local fix | `/forge-fast <request>` | inspect → edit → focused verify |
-| Bug or failing behavior | `/forge-debug <symptom>` | reproduce → root cause → regression test → fix → verify |
-| Research request | `/forge-research <question>` | evidence report; no product-code edits |
-| New behavior or refactor | `/forge-task <request>` | route → research/spec/plan → approval when required → implement → test → review |
-| Pre-merge review | `/forge-review` | five-axis review; resolve blocking findings |
-| npm version/tag/publish | `/forge-release` | release verification; never fast path |
-| Several specialist domains | `/orchestrate` | plan → approval → parallel work → integration verify |
+Use it for symbol search, call paths, architecture, and impact analysis:
 
-### Standard Feature Flow
-
-`/forge-task` manages Spec → Plan → Implement → Review internally and pauses only at the explicit user approval gate before implementation. It does not stop by printing a command for the member to run next.
-
-Workflow files define process and gates. Skills define methods/checklists. Agents provide specialist ownership. Members should invoke the command, not only describe the work in chat.
-
-### Bug Fix Flow
-
-Use `/forge-debug` for regressions, failing tests, exceptions, incorrect output, or any symptom with an unknown root cause. Load `$systematic-debugging`, the `debugger` agent, and `testing-patterns`; reproduce the issue, inspect the code path, test hypotheses, add regression protection, make the smallest root-cause fix, and verify. Use `/forge-review` when the change is cross-file or affects a shared contract.
-
-### Simple Fast Path
-
-Use `/forge-fast` only for one obvious file, an unambiguous result, and no behavior, API, schema, security, CI, dependency, workflow, or release contract change. Before editing, state:
-
-```text
-FAST_PATH: simple-fix
-REASON: [why Spec/Plan/Review are not needed]
-SCOPE: [file or narrow area]
+```bash
+npm install -g codebase-memory-mcp
+codebase-memory-mcp cli index_repository --repo-path .
 ```
 
-This bypasses only Spec, Plan, and the feature/refactor Review gate. It never bypasses inspection or verification. If the scope expands, re-route internally through `forge-task`.
+The index is local state. Keep it out of git unless the team explicitly chooses to share a snapshot.
 
-Claude Code has a Stop hook that checks the standard feature/refactor gate. Codex, Antigravity, and Cursor use the same written routing rules through `AGENTS.md`, `.cursorrules`, and `.agent/rules/GEMINI.md`.
+### RTK
 
-## Optional Tooling
+RTK is the recommended command-output layer, not a workflow engine. Prefer it by default for verbose shell commands:
 
-`init` performs setup and prints what it configured:
+```bash
+cargo install --git https://github.com/rtk-ai/rtk --branch master rtk
+```
 
-- Playwright: install browsers with `npx playwright install` for Node projects, or `pip install playwright && playwright install chromium` when using the Python helper.
-- Auto setup: `thachvd-kit` installs the Codegraph CLI when missing and merges MCP config for Codex, Gemini/Antigravity, and Claude Code.
-- Codex MCP: uses `~/.codex/config.toml` with `[mcp_servers.context7]`, `[mcp_servers.codegraph]`, and `[mcp_servers.playwright]`.
-- Gemini/Antigravity MCP: uses `mcp_config.json` with a top-level `mcpServers` object. The generated config includes `codegraph`, `context7`, and `playwright`.
-- Claude Code MCP: uses `~/.claude.json` with a top-level `mcpServers` object.
-- Codegraph indexes: `.codegraph/` is local state and should not be committed.
-- Native skills: Codex global skills live in `~/.codex/skills/`, Claude Code project skills live in `.claude/skills/`, and the full shared source remains in `.agent/skills/`.
+Examples: `rtk git status`, `rtk npm test`, `rtk git log`. If it is not installed, run the underlying command directly.
 
-## Directory Layout
+## CLI
 
 ```text
-.agent/
-├── agents/
-├── docs/
-│   ├── architecture.md
-│   ├── conventions.md
-│   ├── project.md
-│   ├── tooling.md
-│   └── workflow.md
-├── rules/
-├── skills/
-└── workflows/
+thachvd-kit init [--yes]
+thachvd-kit setup [--no-setup-mcp]
+thachvd-kit doctor
+thachvd-kit prompt
+thachvd-kit --help
 ```
 
-The generated project copies selected native skills to global user folder and project folder:
+`setup` configures MCP entries for detected clients and prints official Superpowers installation guidance. It may install npm-based MCP packages when they are missing. `doctor` is read-only and reports missing integrations without changing the machine.
 
-```text
-~/.codex/skills/
-.claude/skills/
-```
+The project-indexing prompt is saved by `init`, so installing Superpowers or RTK afterward cannot make it disappear. Run `thachvd-kit prompt` whenever you need to print it again.
 
 ## Development
 
 ```bash
 npm install
 npm test
-npm pack --dry-run
-```
-
-## Npm Release Flow
-
-An npm release is never a simple fix. Release only from a clean `main` branch after the change has passed the feature/refactor gates and has been pushed to GitHub.
-
-```bash
-# 1. Verify the clean, pushed source
-git status --short --branch
 npm run release:verify
-
-# 2. Bump patch version, create the version commit and git tag
-npm run release:patch
-
-# 3. Push the version commit and tag
-git push origin main --follow-tags
-
-# 4. Confirm npm authentication, then publish
-npm whoami
-npm run release:publish
-
-# 5. Verify the registry and the installed CLI
-npm view thachvd-kit version
-npx thachvd-kit@<published-version> --help
 ```
 
-`npm run release:patch` runs the verification command first through `preversion`; `npm version patch` then updates `package.json`/`package-lock.json`, creates a commit, and creates a git tag. A published `name@version` cannot be reused, so do not publish until the version and tarball are correct. Use `npm publish --tag beta` for a prerelease channel instead of changing `latest`.
-
-### Which Flow To Use
-
-- **Question/analysis:** answer or inspect only; no files changed, so no spec/plan/review.
-- **Simple fix:** one unambiguous file, no behavior/API/schema/security/CI/release contract change; inspect, edit, run focused verification, summarize.
-- **Feature/refactor:** any new behavior, multiple files, dependency/API/schema/security/CI changes, or work likely over 30 minutes; run Spec → user-approved Plan → Implement → Review → verification.
-- **Multi-domain task:** route through `.agent/workflows/orchestrate.md`.
-- **Release/publish:** only after the relevant implementation flow is complete; run the npm release flow above. Never bypass release verification.
-
-The npm package page updates only after `npm publish`.
+Release only from a clean, verified, pushed `main` branch. `npm publish` requires valid npm authentication and any configured 2FA code.