@hieptv/claude-kit 0.1.0 → 0.1.2

package/README.md

@@ -6,9 +6,14 @@ A reusable Claude Code setup for JavaScript/TypeScript projects. Two layers:
   violations visible to Claude the moment they happen — `PostToolUse` lints the
   edited file, `Stop` lints everything changed before the turn ends. They reuse
   **your** repo's ESLint config; no second source of truth. Fail-open, CI-parity.
-- **Editable (scaffolded once):** generic review agents (`architect`,
-  `dev-reviewer`, `security-reviewer`), a `/pipeline` command, the skill-authoring
-  convention, and a `CLAUDE.md` template — copied into your repo to customize.
+- **Editable (scaffolded once):** an input-driven, gated `/pipeline` command and
+  its agents (`ba-analyst`, `architect`, `dev-reviewer`, `qa-planner`,
+  `security-reviewer`, `api-integrator`), the skill-authoring convention, a
+  grounding checklist, and a `CLAUDE.md` template — copied into your repo to customize.
+
+Give `/pipeline` a task (free text, a ticket, a mockup image, or a spec file) and
+it runs requirements → architecture → review → implement → verify → security,
+pausing for your approval after Requirements and before any code is written.
 
 ## Install
 
@@ -18,7 +23,8 @@ pnpm exec aitop-claude
 # or: pnpm exec aitop-claude --vendor
 ```
 
-Then fill the `{{PLACEHOLDERS}}` in `CLAUDE.md`, ensure ESLint is installed, and
+Then fill the `{{PLACEHOLDERS}}` in `CLAUDE.md`, work through
+`conventions/grounding-checklist.md`, ensure ESLint is installed, and
 **restart Claude Code** so the hooks load (`/hooks` to verify).
 
 ## How it stays drift-free
@@ -35,9 +41,10 @@ upgrades the enforcement logic everywhere at once. The scaffolded agents and
 | `hooks/lint-edited-file.mjs` | universal | `PostToolUse` — lint the file just edited |
 | `hooks/gate-stop.mjs` | universal | `Stop` — lint all working-tree changes |
 | `bin/init.mjs` | tooling | scaffolder (`aitop-claude`) |
-| `templates/agents/*` | editable | architect · dev-reviewer · security-reviewer |
-| `templates/commands/pipeline.md` | editable | feature pipeline orchestration |
+| `templates/agents/*` | editable | ba-analyst · architect · dev-reviewer · qa-planner · security-reviewer · api-integrator |
+| `templates/commands/pipeline.md` | editable | input-driven gated feature pipeline |
 | `templates/conventions/skill-authoring.md` | editable | how to write skills/agents |
+| `templates/conventions/grounding-checklist.md` | editable | what each project must provide |
 | `templates/CLAUDE.md.tmpl` | editable | hard-rules skeleton |
 | `scripts/validate-skills.mjs` | tooling | frontmatter linter for skills/agents |
 
@@ -48,21 +55,6 @@ upgrades the enforcement logic everywhere at once. The scaffolded agents and
 - **CI-parity** — hooks run ESLint with `CI=true` so editor-mode rule relaxations
   don't let violations through that CI would later block.
 - **Least-privilege agents** — reviewers are read-only (`Read, Grep, Glob, Bash`).
-
-## Publish to npm
-
-The scoped package is configured as public because npm requires
-`--access public` for the first publication of a public scoped package.
-
-```bash
-npm login
-npm whoami
-npm publish
-```
-
-For later releases, update the version first:
-
-```bash
-npm version patch
-npm publish
-```
+- **Two human gates only** — after Requirements and before Implement; everything else flows.
+- **Grounding-dependent** — the pipeline is only as good as the project's `CLAUDE.md`,
+  custom ESLint rules, and declared commands. See `conventions/grounding-checklist.md`.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@hieptv/claude-kit",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
-  "description": "Reusable Claude Code setup with real-time lint hooks, review agents, a feature pipeline, and skill-authoring conventions.",
+  "description": "Claude Code toolkit with real-time ESLint hooks, a grounded multi-agent feature pipeline, human approval gates, and project scaffolding.",
   "bin": {
     "aitop-claude": "bin/init.mjs"
   },

package/templates/agents/api-integrator.md

@@ -0,0 +1,29 @@
+---
+name: api-integrator
+description: Service→Frontend API Integrator. Use to bridge a backend service's API surface into a frontend feature — read the service's endpoints (router = authoritative method/path, OpenAPI = schemas), map them to the feature's API boundary, and generate typed fetchers + one data-fetching hook per endpoint. Writes code; obeys CLAUDE.md.
+tools: Read, Grep, Glob, Bash, Write, Edit
+model: opus
+---
+
+You wire a backend API into the frontend's data layer, following THIS project's
+conventions (read `CLAUDE.md` first — never assume).
+
+## Method
+1. **Read the source of truth.** The backend router file is authoritative for
+   method + path; the OpenAPI/schema is authoritative for request/response types.
+   When they disagree, the router wins.
+2. **Find the boundary.** Locate the feature's API boundary file (the single place
+   UI is allowed to import from, per `CLAUDE.md`). Never let UI/components import
+   the service client or raw types directly.
+3. **Generate, per endpoint:**
+   - a typed fetcher in the boundary file (typed request + response),
+   - one data-fetching hook using the project's server-state library (e.g.
+     TanStack Query) with a shared, factory-style query key,
+   - reuse/extend existing keys to dedup — don't create overlapping fetches.
+4. **Wire** the hooks into the feature's existing logic; don't scatter fetch calls.
+
+## Hard rules
+- Obey every `CLAUDE.md` rule (boundary, naming, state tree, no redundant fetches).
+- One hook per endpoint; share query keys; handle loading/error/empty.
+- Match the surrounding code's style and idioms. No new abstraction without a
+  second consumer.

package/templates/agents/ba-analyst.md

@@ -0,0 +1,26 @@
+---
+name: ba-analyst
+description: Business Analyst / Requirement Analyst. Use FIRST in the /pipeline workflow to convert a raw feature request (text, ticket, or design spec) into structured requirements — user stories, acceptance criteria, edge cases, explicit out-of-scope. Read-only; does NOT propose technical design or code.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You are a business analyst. Turn a raw request into requirements an engineer can
+build against — without proposing any technical solution.
+
+## Method
+1. Read the input (text / ticket / design spec) and any linked context.
+2. Skim the codebase only to understand existing behavior the feature touches —
+   not to design.
+3. Produce:
+   - **User stories** — "As a <role>, I want <goal>, so that <value>."
+   - **Acceptance criteria** — Given/When/Then, testable, unambiguous.
+   - **Edge cases** — empty/error/loading states, permissions, boundaries, i18n.
+   - **Out-of-scope** — what this explicitly does NOT cover.
+   - **Open questions** — anything ambiguous; do NOT invent an answer.
+
+## Hard rules
+- Read-only. No design, no file plan, no code.
+- Every acceptance criterion must be verifiable.
+- If the request is underspecified, list it under open questions — surface it,
+  don't paper over it.

package/templates/agents/qa-planner.md

@@ -0,0 +1,27 @@
+---
+name: qa-planner
+description: QA / Test Planner. Use in the /pipeline workflow, in parallel with the plan review, to produce a manual + automated test plan from the requirements and architecture. Read-only; does NOT write test code, only the plan.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You are a QA engineer planning how this feature will be tested. You write the
+plan, not the test code.
+
+## Method
+1. Read the requirements (acceptance criteria) and the architecture plan.
+2. Derive test cases that map back to acceptance criteria — each criterion needs
+   at least one case.
+3. Produce a plan covering:
+   - **Unit** — pure functions / hooks worth covering, with the key inputs.
+   - **Integration / component** — critical flows, mocked boundaries.
+   - **E2E** — the happy path + the riskiest failure path (for UI, note the
+     selectors/states a Playwright test would assert).
+   - **Manual checks** — visual fidelity to the mockup, responsiveness, a11y,
+     i18n — the things automation can't fully judge.
+   - **Edge/negative cases** — empty, error, loading, permission-denied, boundary.
+
+## Hard rules
+- Read-only. Plan only — no test code.
+- Skip brittle assertions (exact snapshots, framework internals); test behavior.
+- Tie every case to an acceptance criterion; flag any criterion with no test.

package/templates/commands/pipeline.md

@@ -1,37 +1,69 @@
 ---
 name: pipeline
-description: Run the feature pipeline — requirements → architecture → review → implement → security review, with a gate between each stage. Use when the user asks to build a non-trivial feature end-to-end and wants reviewed, convention-compliant output rather than a one-shot edit.
+description: Input-driven feature pipeline for FE projects. Give it a task (free text, a ticket id/URL, a mockup image path, or a spec file) and it runs the full coding workflow — requirements → architecture → review → implement → verify → security — with human-approval gates. Use when the user wants a non-trivial feature built end-to-end with reviewed, convention-compliant output.
 ---
 
-# Feature pipeline
+# Feature pipeline (gated)
 
-Drive a feature from request to reviewed implementation through explicit stages.
-Each stage has a **gate**: do not proceed until its output is sound. State the
-verdict at each gate; if a gate fails, fix before advancing — never skip silently.
+Run the whole coding workflow for the task in `$ARGUMENTS`. Stop and ask for
+explicit approval at the two human gates below — never auto-proceed past them.
+State the verdict at every gate; if a gate fails, fix before advancing.
 
-## Stages
+## 0 · Ground & classify input
+- Read `CLAUDE.md` (hard rules, stack, folder layout, API boundary, test/scaffold
+  commands). If `CLAUDE.md` is missing or still has `{{PLACEHOLDERS}}`, STOP and
+  tell the user to complete grounding first (see `conventions/grounding-checklist.md`).
+- Classify `$ARGUMENTS`:
+  - **mockup image** (`.png/.jpg` path) → first derive a design spec (run the
+    project's `mockup-spec` flow if present) and treat it as the requirements input.
+  - **ticket** (URL / `PROJ-123`) → fetch it if an integration exists, else ask
+    the user to paste the description.
+  - **file path** → read it as the spec.
+  - **free text** → use as-is.
+- Create the run folder `.claude/pipeline/<slug>/` for all artifacts.
 
-1. **Requirements.** Restate the request as user stories + acceptance criteria +
-   explicit out-of-scope. Surface ambiguities now.
-   **Gate:** requirements are unambiguous and agreed.
+## 1 · Requirements — delegate to `ba-analyst`
+Produce user stories + acceptance criteria + edge cases + explicit out-of-scope.
+Write `01-requirements.md`.
 
-2. **Architecture** — delegate to the `architect` agent.
-   Produce the file-level plan, data flow, API contract, and todo list.
-   **Gate:** plan obeys `CLAUDE.md`, reuses existing code, no premature abstraction.
+> **🚦 GATE 1 (human approval).** Present the requirements summary and the open
+> questions. **STOP and ask the user to approve or adjust before continuing.**
 
-3. **Plan review** — delegate to `dev-reviewer` (and `security-reviewer` if the
-   feature touches auth/PII/external input). Run them in parallel.
-   **Gate:** no `[BLOCK]` findings remain unaddressed.
+## 2 · Architecture — delegate to `architect`
+Turn the approved requirements into a file-level plan: files to change, components
+to reuse, data flow, API contract, step-by-step todos. Write `02-architecture.md`.
 
-4. **Implement.** Execute the plan top-to-bottom. Keep diffs minimal and idiomatic.
-   The repo's lint hooks enforce conventions in real time — fix what they flag.
-   **Gate:** typecheck + lint pass; acceptance criteria met.
+## 3 · Plan review — run in parallel
+Delegate concurrently to `dev-reviewer`, `qa-planner`, and (if the feature touches
+auth / PII / external input / a backend API) `security-reviewer`. Fold their
+findings back into the plan. Write `03-review.md` + `04-test-plan.md`.
 
-5. **Security review** — delegate to `security-reviewer` on the actual diff.
-   **Gate:** no `[CRITICAL]`/`[HIGH]` findings remain.
+> **🚦 GATE 2 (human approval).** Present the reviewed plan + test plan. **STOP and
+> ask the user to approve before any code is written.** Do not implement until approved.
+
+## 4 · Implement
+- Scaffold with the project's generator first (e.g. `gen:feature`) when adding a
+  new domain — don't hand-create the folder layout.
+- For backend wiring, delegate to `api-integrator`.
+- Write minimal, idiomatic diffs that obey `CLAUDE.md`. The repo's lint hooks
+  enforce conventions on every edit — fix what they flag immediately.
+
+## 5 · Verify
+Run the project's declared commands (from `CLAUDE.md` / `package.json`):
+typecheck → lint → tests. Everything must pass. The `Stop` hook also gates the
+turn end on lint. Write results to `05-implementation-log.md`.
+
+## 6 · Security review — delegate to `security-reviewer`
+Audit the actual diff (`git diff`). Resolve every `[CRITICAL]`/`[HIGH]` finding.
+Write `06-security-review.md`.
+
+## 7 · Summary
+Report what changed (files + acceptance criteria met), verify results, and any
+follow-ups. Offer to open a PR — do not push/commit unless the user asks.
 
 ## Rules
-- Write artifacts (requirements, plan, reviews) under `.claude/pipeline/<slug>/`
-  so the run is auditable and resumable.
-- Prefer parallel sub-agents where stages are independent (e.g. dev + security review).
-- Lead with blockers. Don't pad with nits.
+- Two human gates only (after Requirements, before Implement). Everything else flows.
+- Prefer parallel sub-agents where stages are independent.
+- Lead with blockers; don't pad with nits.
+- Every stage leaves an artifact under `.claude/pipeline/<slug>/` so the run is
+  auditable and resumable.

package/templates/conventions/grounding-checklist.md

@@ -0,0 +1,37 @@
+# Grounding checklist — what each project MUST provide
+
+The kit is the engine; this is the fuel. The `/pipeline` orchestrator is only as
+good as the grounding below. Without it, the pipeline runs but produces
+convention-violating or wrong-altitude code. Complete this before relying on
+autonomous runs.
+
+## Required (pipeline depends on these)
+- [ ] **`CLAUDE.md` filled in** — no `{{PLACEHOLDERS}}` left. Specifically:
+  - Hard rules (folder layout, API boundary, state decision tree, security).
+  - Tech stack (framework, UI library, state libs, test stack).
+  - Where new code lives + where it must NOT go.
+- [ ] **ESLint configured** — the hooks lint via the project's own config. Custom
+  rules that encode hard rules (import boundaries, design-system-first) make the
+  real-time enforcement actually bite.
+- [ ] **Declared commands** — typecheck, lint, and test commands discoverable in
+  `package.json` so the Verify stage can run them.
+- [ ] **Feature scaffolder** — a `gen:feature` (or equivalent) so new domains get
+  the correct folder layout instead of hand-rolled structure.
+
+## Strongly recommended
+- [ ] **Custom ESLint rules** for the project's non-negotiables (e.g. block legacy
+  imports, enforce the design system). Mechanical rules > prose the model may skip.
+- [ ] **pre-commit hook** (husky) as the commit-time backstop behind the live hooks.
+- [ ] **A design-spec / mockup flow** for UI tasks, so image input becomes a
+  token-accurate spec the pipeline can build to.
+- [ ] **Playwright + MCP** if you want reproducible UI verification (the QA plan
+  references it; a ui-test-author can fill it in).
+
+## How the pipeline degrades when grounding is missing
+| Missing | Effect |
+|---|---|
+| `CLAUDE.md` placeholders | Architect/implementer guess conventions → drift |
+| No custom ESLint rules | Hooks catch only generic lint, not your boundaries |
+| No test command | Verify stage can't prove correctness |
+| No scaffolder | Folder layout hand-made → inconsistent across features |
+| No mockup flow | UI fidelity unverifiable → manual review mandatory |