thachvd-kit 1.0.37 → 1.0.38

package/README.md

@@ -27,6 +27,218 @@ thachvd-kit doctor
 
 After the first skill install, run `/setup-matt-pocock-skills` once inside your AI client to configure the issue tracker, triage labels, and generated docs location — thachvd-kit does not simulate that skill.
 
+## Brownfield System Specs
+
+This workflow is **opt-in**. Normal `thachvd-kit init/upgrade -> setup -> development` behavior is unchanged unless you run `thachvd-kit spec init`.
+
+The same happy path works for **one repository or many**:
+
+```bash
+cd your-repo-or-workspace
+
+thachvd-kit spec init --language vi   # optional; omit for English
+thachvd-kit spec index
+thachvd-kit spec discover
+
+# In your AI client:
+# /system-discovery
+
+# Human-review:
+# system-specs/architecture/capability-map.md
+
+thachvd-kit spec reverse
+
+# In your AI client:
+# /system-reverse-engineer
+
+thachvd-kit spec verify
+
+# In your AI client:
+# /system-spec-review
+
+thachvd-kit spec check
+thachvd-kit spec link
+```
+
+### Documentation language
+
+Use `--language vi` when you want human-facing specs in Vietnamese:
+
+```bash
+thachvd-kit spec init --language vi
+```
+
+If Vietnamese is your normal preference across projects, set it once at user level:
+
+```bash
+thachvd-kit config set spec-language vi
+```
+
+Then plain `thachvd-kit spec init` uses Vietnamese by default. A project-level `--language en|vi` always overrides the user default. Use `thachvd-kit config show` to inspect the current setting.
+
+The setting is stored in `.thachvd/system.json` and reused by `/system-discovery`, `/system-reverse-engineer`, and `/system-spec-review`. Only prose/headings/explanations are localized; code identifiers, class/function names, API routes, event/queue names, database/schema names, file paths, commands, and source anchors remain exactly as they appear in source. Default is `en`.
+
+### Analysis profiles
+
+Profiles adjust what discovery/reverse/review should inspect most carefully. They do **not** override code/tests and they do not hide behavior outside the selected profile.
+
+The default is `auto`, so the normal command remains:
+
+```bash
+thachvd-kit spec init
+```
+
+In `auto` mode, the agent infers a practical profile for each repository from code/config evidence. A multi-repo system can therefore contain a backend API, frontend app, worker and infra repo without forcing one profile across all of them.
+
+You can explicitly bias the checklist when a project is known:
+
+```bash
+thachvd-kit spec init --profile backend
+thachvd-kit spec init --profile frontend
+thachvd-kit spec init --profile fullstack
+thachvd-kit spec init --profile mobile
+thachvd-kit spec init --profile infra
+```
+
+Current emphasis:
+
+- `backend`: routes/RPC, auth/policies, services/domain, DB/migrations/transactions, queues/jobs/events/schedulers, retries/idempotency/concurrency, external clients and rollback/failure behavior.
+- `frontend`: routes/navigation, components/pages, state/data clients, forms/validation, auth/session, accessibility, analytics, loading/error states, browser storage and runtime/build config.
+- `fullstack`: both sides plus client/server contracts, shared schemas/types, auth propagation, SSR/BFF/server actions and end-to-end failures.
+- `mobile`: app lifecycle/background work, offline/sync, local storage, permissions, push/deep links, auth refresh, platform/device integrations and release config.
+- `infra`: IaC, environments, CI/CD, secrets/IAM/networking, state backends, observability, scaling, deployment order, rollback/recovery and destructive-change safeguards.
+
+Set a user default if you frequently work on the same class of project:
+
+```bash
+thachvd-kit config set spec-profile backend
+```
+
+Precedence is: explicit `--profile` → user config → `auto`.
+
+### Automatic repository detection
+
+`spec init` does not require `--repo` in the normal case:
+
+- if the current directory is a Git repository, it is treated as a single-repo system;
+- otherwise, direct child Git repositories are detected as a multi-repo system;
+- `--repo` remains available only as an override for unusual directory layouts.
+
+For a single repo, `system-specs/` lives in that repo. For multiple repos, run from the common workspace directory; that workspace owns `.thachvd/system.json` and `system-specs/`.
+
+For team use, make sure the configured `spec_root` is version-controlled. In a single repo this happens naturally. In a multi-repo workspace whose parent directory is not itself a Git worktree, use a dedicated docs/spec Git repository or set `--spec-root` to a location that is committed. `thachvd-kit spec doctor` warns when the spec root is not in a committed Git worktree; the kit does not silently initialize or choose a remote repository for you.
+
+`spec init` also installs the bundled `/system-discovery`, `/system-reverse-engineer`, and `/system-spec-review` skills into the workspace so the flow can run from the common parent directory.
+
+### What the AI phases do
+
+`/system-discovery` builds the coarse AS-IS map first:
+
+- system overview
+- repository responsibilities
+- capability map
+- cross-repository integrations
+- domain glossary
+
+A human reviews the capability boundaries before deep documentation begins.
+
+Then `thachvd-kit spec reverse` writes the handoff for `/system-reverse-engineer`. With **no capability argument**, one invocation processes the entire approved capability map and creates/updates:
+
+- `system-specs/capabilities/<capability>/prd.md`
+- `system-specs/capabilities/<capability>/design.md`
+- real cross-repository flow specs under `system-specs/flows/`
+- real cross-boundary contracts under `system-specs/contracts/`
+
+Internally the agent works capability-by-capability, persists progress to `system-specs/_meta/reverse-progress.json`, and resumes incomplete capabilities on later invocations. The user does **not** need to manually run one command per module.
+
+A capability argument is only a targeted refresh:
+
+```bash
+thachvd-kit spec reverse booking
+```
+
+Use that later when only Booking changed or needs to be re-documented.
+
+### Independent verification and drift detection
+
+After reverse engineering finishes:
+
+```bash
+thachvd-kit spec verify
+# In your AI client: /system-spec-review
+thachvd-kit spec check
+```
+
+`/system-spec-review` independently reconstructs implementation coverage and tries to find missing behavior, unsupported claims, weak/broken source anchors, PRD/design contradictions, and cross-repository contract gaps. It writes:
+
+- `system-specs/_meta/review.md`
+- `system-specs/_meta/verification.json`
+
+The verification JSON stores a full-system repository snapshot plus **capability-specific `verified_commits` and repository-relative `source_paths`**. `spec check` compares each capability against its own baseline, including committed, staged, unstaged, and untracked changes, so re-verifying one capability cannot accidentally make unrelated specs look current.
+
+Use `thachvd-kit spec check --strict` in CI when stale/unknown specs should fail the check.
+
+For an incremental refresh:
+
+```bash
+thachvd-kit spec reverse booking
+# /system-reverse-engineer
+thachvd-kit spec verify booking
+# /system-spec-review
+thachvd-kit spec check
+```
+
+Only Booking's verification baseline advances; unrelated capabilities keep their previous verified commits.
+
+The reverse author is not allowed to call its own output independently verified; only the review phase may mark a capability `verified`.
+
+### Spec health check
+
+`thachvd-kit spec doctor` is read-only and summarizes the documentation system in one place:
+
+- configured repos and Git HEAD availability
+- Codebase Memory availability
+- system-spec skills installed on agent surfaces
+- capability map presence
+- reverse checkpoint progress
+- independent verification/review metadata
+- current drift state
+- whether the spec root is version-controlled
+- AGENTS.md links
+
+```bash
+thachvd-kit spec doctor
+thachvd-kit spec doctor --strict
+```
+
+`--strict` exits non-zero when any WARN/ERROR remains, which is useful for CI or release gates.
+
+### Optional Shinpr recipe integration
+
+`recipe-reverse-engineer` is no longer part of the required flow. If you use Claude Code and want its extra generate -> verify -> review -> revise loop for individual implementation scopes, install it once:
+
+```bash
+thachvd-kit spec recipe-setup
+```
+
+The bundled `/system-reverse-engineer` skill may use that helper when available, but it still works without it.
+
+### Flow summary
+
+1. `spec init` auto-detects one or many repos and creates the workspace/spec structure.
+2. `spec index` indexes all configured repos with codebase-memory-mcp.
+3. `spec discover` creates the handoff for `/system-discovery`.
+4. Human review confirms the system/capability boundaries.
+5. `spec reverse` creates/resumes the whole-system `/system-reverse-engineer` checkpoint.
+6. The author agent writes AS-IS PRD/design/flow/contract docs using fixed templates.
+7. `spec verify` creates the handoff for independent `/system-spec-review`.
+8. The reviewer writes machine-readable verification/provenance metadata.
+9. `spec check` detects code/spec drift deterministically from Git.
+10. `spec doctor` provides a read-only health summary for the spec system.
+11. `spec link` adds an idempotent managed block to each repo's `AGENTS.md` so future agents discover and check the reviewed system specs. By default it refuses to link when any capability is not independently `verified`; `--allow-unverified` is an explicit escape hatch.
+
+Observed behavior from code/tests and undocumented business rationale must remain distinct. Existing human-edited spec docs are not overwritten by `spec init --yes`.
+
 ## Generated Files
 
 - `AGENTS.md`: shared project instructions.
@@ -141,12 +353,27 @@ Examples: `rtk git status`, `rtk npm test`, `rtk git log`. If it is not installe
 thachvd-kit init [--yes]
 thachvd-kit upgrade [--dry-run]
 thachvd-kit global [--dry-run] [--antigravity-only|--codex-only]
+thachvd-kit config show
+thachvd-kit config set spec-language en|vi
+thachvd-kit config unset spec-language
+thachvd-kit config set spec-profile auto|backend|frontend|fullstack|mobile|infra
+thachvd-kit config unset spec-profile
 thachvd-kit setup [--no-setup-mcp] [--no-setup-hook] [--no-install-rtk] [--no-index] [--no-install-skills]
 thachvd-kit doctor
 thachvd-kit prompt
 thachvd-kit skills install [--dry-run]
 thachvd-kit skills check
 thachvd-kit skills update [--dry-run]
+thachvd-kit spec init [--name NAME] [--language en|vi] [--profile auto|backend|frontend|fullstack|mobile|infra] [--repo PATH ...] [--spec-root PATH] [--yes]
+thachvd-kit spec index [--repo NAME ...] [--dry-run]
+thachvd-kit spec discover
+thachvd-kit spec reverse [CAPABILITY] [--reset]
+thachvd-kit spec verify [CAPABILITY]
+thachvd-kit spec check [--strict]
+thachvd-kit spec doctor [--strict]
+thachvd-kit spec recipe-setup [--fullstack] [--dry-run]   # optional Claude Code helper
+thachvd-kit spec link [--dry-run] [--allow-unverified]
+thachvd-kit spec status
 thachvd-kit --help
 ```
 
@@ -162,14 +389,17 @@ npm test
 npm run release:verify
 ```
 
-Release only from a clean, verified, pushed `main` branch. `npm publish` requires valid npm authentication and any configured 2FA code.
-
-## Native Workflow Skills
-
-The workflow layer combines Matt Pocock's planning and implementation skills with thachvd-kit's bundled native skills. `thachvd-kit setup` and `thachvd-kit skills install` install the native set to both `.agents/skills/` and `.claude/skills/`.
-
-- `/using-git-worktrees` is opt-in workspace isolation; an explicit choice to work on the current branch always wins.
-- `/subagent-driven-development` is an alternative executor to `/implement` for plans with multiple relatively independent tasks. It uses bundled cross-platform Node entrypoints on Windows and falls back to `/implement` when subagent dispatch is unavailable.
-- `/finishing-a-development-branch` verifies and hands off a branch, cleaning only manually managed project-local worktrees safely.
-
-`thachvd-kit skills update` refreshes native skills from bundled repository copies and never fetches Superpowers at runtime. See `THIRD_PARTY_NOTICES.md` for recorded upstream provenance.
+Release only from a clean, verified, pushed `main` branch. `npm publish` requires valid npm authentication and any configured 2FA code.
+
+## Native Workflow Skills
+
+The workflow layer combines Matt Pocock's planning and implementation skills with thachvd-kit's bundled native skills. `thachvd-kit setup` and `thachvd-kit skills install` install the native set to both `.agents/skills/` and `.claude/skills/`.
+
+- `/using-git-worktrees` is opt-in workspace isolation; an explicit choice to work on the current branch always wins.
+- `/subagent-driven-development` is an alternative executor to `/implement` for plans with multiple relatively independent tasks. It uses bundled cross-platform Node entrypoints on Windows and falls back to `/implement` when subagent dispatch is unavailable.
+- `/finishing-a-development-branch` verifies and hands off a branch, cleaning only manually managed project-local worktrees safely.
+- `/system-discovery` builds the reviewed AS-IS repo/capability/integration map for a brownfield system with one or many repositories, using Codebase Memory MCP as the primary structural source.
+- `/system-reverse-engineer` turns the approved map into PRD/design/flow/contract specs for the whole system, using a durable checkpoint so large systems can resume safely; a named capability is only a targeted refresh.
+- `/system-spec-review` independently verifies coverage/evidence and writes commit/source-path provenance used by `spec check` for drift detection.
+
+`thachvd-kit skills update` refreshes native skills from bundled repository copies and never fetches Superpowers at runtime. See `THIRD_PARTY_NOTICES.md` for recorded upstream provenance.