@wazir-dev/cli 1.0.0

package/docs/readmes/features/skills/debugging.md

@@ -0,0 +1,148 @@
+# wz:debugging
+
+> Observe. Hypothesize. Test. Fix. In that order, every time. No guesswork.
+
+| Property | Value |
+|---|---|
+| **ID** | `wz:debugging` |
+| **Type** | Rigid |
+| **Trigger** | Behavior is wrong, verification fails, or a test produces unexpected output |
+| **Failure mode** | Random fixes applied without a hypothesis, producing noise and masking root causes |
+
+## Purpose
+
+`wz:debugging` replaces guesswork with a disciplined four-step loop. The core insight is that most debugging failures are not failures of knowledge — they are failures of process. Agents (and humans) reach for fixes before they have clearly stated what is failing, why they think it's failing, and what experiment would prove or disprove that hypothesis. This skill enforces the correct order.
+
+## When to Invoke
+
+- A test fails unexpectedly during `wz:tdd` GREEN or REFACTOR.
+- `wz:verification` produces a failure.
+- A command returns an unexpected exit code or output.
+- Behavior in production or test diverges from specification.
+
+> [!TIP]
+> `wz:using-skills` routes "Fix this bug" and "Why is this failing?" directly here. If you find yourself changing code without having first written down the exact failure and a ranked list of hypotheses, invoke this skill.
+
+## When NOT to Invoke
+
+- The failure is fully explained by a known, simple cause (e.g., a missing import you just identified). Fix it directly and rerun verification.
+- You are exploring intentionally open-ended behavior — use `scan-project` instead.
+
+## Phases
+
+### 1. Observe
+
+Record the exact failure state before touching anything.
+
+| Observe item | Example |
+|---|---|
+| Exact failure message | `TypeError: Cannot read properties of undefined (reading 'tokens')` |
+| Reproduction path | `npm test -- --grep rate-limit` → line 42 |
+| Command output | Full stderr/stdout captured |
+| Current assumptions | "Redis client is initialized before middleware runs" |
+
+Do not skip this step to "save time". Vague failure descriptions produce vague fixes.
+
+### 2. Hypothesize
+
+List 2-3 plausible root causes and rank them by likelihood.
+
+```
+Hypothesis 1 (most likely): Redis client not yet connected when middleware invoked — race condition on startup
+Hypothesis 2: Test setup calls middleware before Redis mock is initialized
+Hypothesis 3: `tokens` property missing from bucket response shape (API change)
+```
+
+Do not proceed to testing with only one hypothesis. If you only have one, you are already anchored — generate two more.
+
+### 3. Test
+
+Design the **smallest discriminating check** that confirms or rejects the top hypothesis.
+
+- One change at a time.
+- The check must be able to falsify the hypothesis — if the result would be the same either way, it's not a discriminating check.
+
+```bash
+# Testing Hypothesis 1: Add connection-ready log before middleware
+# If log never prints before the error, hypothesis 1 is confirmed
+```
+
+Run the check. Record the result. Update your hypothesis ranking.
+
+### 4. Fix
+
+Apply the minimum corrective change.
+
+- Do not fix adjacent issues at the same time.
+- Rerun the originally failing check after the fix.
+- Rerun the broader relevant verification set.
+
+```bash
+npm test -- --grep rate-limit   # originally failing check
+npm test                        # broader set
+```
+
+## Rules
+
+| Rule | Why |
+|---|---|
+| Change one thing at a time | Multiple simultaneous changes make it impossible to know what fixed the problem |
+| Keep evidence for each failed hypothesis | Audit trail prevents re-investigating the same dead ends |
+| If three cycles fail, record the blocker | Inventing certainty after three failed cycles produces confident wrong answers |
+
+## Three-Cycle Limit
+
+If three complete Observe → Hypothesize → Test → Fix cycles have not resolved the failure:
+
+1. Do not apply a fourth speculative fix.
+2. Record the blocker in the active execution artifact or handoff:
+   - What was tried
+   - What each attempt produced
+   - What remains unknown
+3. Escalate to operator or flag for manual investigation.
+
+## Input
+
+- Failing command output (exact)
+- Reproduction steps
+- Current codebase state
+
+## Output
+
+| Artifact | Description |
+|---|---|
+| Observed failure (documented) | Exact failure, reproduction path, assumptions |
+| Hypothesis log | Ranked hypotheses, test results per hypothesis |
+| Fix applied | Minimum corrective change |
+| Verification result | Passing check output |
+
+## Example
+
+**Scenario:** `npm test -- --grep "rate-limit returns 429"` fails with `expected 200 to equal 429`.
+
+```
+1. OBSERVE
+   Failure: middleware returns 200 instead of 429 when bucket empty
+   Command: npm test -- --grep "rate-limit returns 429"
+   Output: AssertionError: expected 200 to equal 429
+   Assumption: exhaustBucket() correctly empties the Redis key
+
+2. HYPOTHESIZE
+   H1: exhaustBucket() in test setup is not actually writing to the mock Redis store
+   H2: Middleware reads tokens before bucket is exhausted (async issue)
+   H3: Token bucket logic has an off-by-one — allows one extra request
+
+3. TEST H1
+   Add console.log in exhaustBucket to print the mock store state after calling it
+   Result: mock store shows tokens = 1, not 0 — H1 is the problem
+
+4. FIX
+   exhaustBucket() was calling set() with tokens=1 instead of 0 (copy-paste error)
+   Fix: change exhaustBucket to set tokens=0
+   Rerun: npm test -- --grep "rate-limit returns 429" → 1 passing
+   Rerun: npm test → all passing
+```
+
+## Integration
+
+`wz:debugging` activates whenever `wz:tdd` or `wz:verification` encounters a failure it cannot immediately explain. After debugging resolves the issue, return to the interrupted skill (TDD or verification) and continue from where it was interrupted.

package/docs/readmes/features/skills/design.md

@@ -0,0 +1,120 @@
+# wz:design
+
+> Guide the designer role through the open-pencil MCP workflow to produce production-ready design artifacts from an approved spec.
+
+| Property | Value |
+|---|---|
+| **ID** | `wz:design` |
+| **Type** | Flexible |
+| **Trigger** | Design phase — after spec approval, before plan |
+| **Failure mode** | Missing `.fig` file, hardcoded values, absolute positioning |
+| **Requires** | open-pencil MCP server + Bun runtime |
+
+## Purpose
+
+`wz:design` operationalizes the designer role by providing a concrete MCP tool workflow for creating visual design artifacts from an approved spec. It produces a design system grounded in tokens (no hardcoded hex values), auto-layout frames (no absolute positioning), and exportable artifacts that feed directly into frontend implementation.
+
+When open-pencil is unavailable, this skill provides a graceful degradation path so the workflow does not stall.
+
+## When to Invoke
+
+- The `design` workflow phase is active.
+- An approved spec artifact exists.
+- open-pencil MCP server is running (`openpencil-mcp` or `openpencil-mcp-http`).
+- Bun runtime is installed.
+
+> [!TIP]
+> Check prerequisites before starting: `which bun` and confirm the MCP server is reachable. A failed design phase that produces nothing is worse than skipping to text-only spec documentation.
+
+## When NOT to Invoke
+
+- No approved spec exists — complete the `specify` phase first.
+- open-pencil MCP server is not running and Bun is not installed — see the Unavailable Fallback section below.
+- The design already exists and only code generation is needed — jump to the Export step.
+
+## Phases
+
+| Step | MCP Tools | Description |
+|---|---|---|
+| 1. Read the spec | — | Identify screens, components, and flows to design |
+| 2. Create document | `new_document` or `open_file` | Start fresh `.fig` or open existing |
+| 3. Set up design tokens | `create_collection`, `create_variable` | Colors, spacing, typography from spec/brand |
+| 4. Build frames | `create_shape (FRAME)`, `set_layout` | One frame per screen/component, auto-layout on all |
+| 5. Populate content | `render` (JSX), `create_shape`, `set_fill`, `set_text` | Content within frames |
+| 6. Bind tokens | `bind_variable` | Connect fills/strokes/text to design variables — no hardcoded values |
+| 7. Export artifacts | `export_image`, `export_svg` | Screenshots and vectors |
+| 8. Save | `save_file` | Persist the `.fig` |
+| 9. Generate code | CLI `open-pencil export` | Tailwind JSX output |
+| 10. Extract tokens | `analyze_colors`, `analyze_typography`, `analyze_spacing` | Design tokens JSON |
+
+## MCP Tool Reference
+
+| Phase | Tools |
+|---|---|
+| Read | `get_page_tree`, `find_nodes`, `get_node`, `list_variables` |
+| Create | `create_shape`, `render` (JSX), `create_page`, `create_component` |
+| Style | `set_fill`, `set_stroke`, `set_layout`, `set_font`, `set_effects` |
+| Variables | `create_collection`, `create_variable`, `bind_variable` |
+| Export | `export_image`, `export_svg`, `save_file` |
+| Analyze | `analyze_colors`, `analyze_typography`, `analyze_spacing`, `analyze_clusters` |
+| Diff | `diff_create`, `diff_show` |
+
+## Required Outputs
+
+| Artifact | Description |
+|---|---|
+| `.fig` design file | Saved and committed |
+| Tailwind JSX export | Component code with Tailwind classes |
+| HTML + CSS export | Fallback implementation-ready code |
+| Design tokens JSON | Colors, spacing, typography as structured data |
+| Screenshot PNGs | One per top-level frame, for visual verification |
+
+## Rules
+
+1. Every design must have auto-layout on all frames — no absolute positioning except icons/decorations.
+2. Use design variables for all colors and spacing — no hardcoded hex values.
+3. Export screenshots after every major change for visual verification.
+4. Create a `diff_create` snapshot before modifications to enable rollback.
+
+## Unavailable Fallback
+
+If open-pencil MCP server is not running or Bun is not installed:
+
+1. Skip this phase — do not attempt to produce `.fig` artifacts with unavailable tooling.
+2. Document the design intent in prose within the spec artifact.
+3. Skip the `design-review` workflow as well.
+4. Proceed directly to planning with text-only design specifications.
+
+> [!WARNING]
+> Do not produce partial design artifacts with absolute positioning or hardcoded values because tooling was unavailable. A clean text spec is more useful to implementors than a malformed design file.
+
+## Example
+
+**Scenario:** Approved spec for a dashboard screen with a data table and filter sidebar.
+
+```
+Agent: Invoking wz:design for dashboard screen.
+
+Step 2: new_document() → design.fig created
+Step 3: create_collection("tokens") → create_variable("color/primary", "#0066CC")
+        create_variable("spacing/md", 16)
+Step 4: create_shape(FRAME, "Dashboard") → set_layout(direction=HORIZONTAL, gap=spacing/md)
+        create_shape(FRAME, "Sidebar") → set_layout(direction=VERTICAL)
+        create_shape(FRAME, "Content") → set_layout(direction=VERTICAL)
+Step 5: render(<DataTable columns={...} />) → rendered in Content frame
+Step 6: bind_variable(fill → color/primary) on all primary buttons
+Step 7: export_image("Dashboard") → dashboard.png
+Step 8: save_file("design.fig")
+Step 9: open-pencil export design.fig -f jsx --style tailwind → Dashboard.jsx
+Step 10: analyze_colors() → tokens.json
+```
+
+## Integration
+
+`wz:design` sits between spec and planning:
+
+```
+specify (approved spec) → wz:design (design artifacts) → design_review → wz:writing-plans
+```
+
+The Tailwind JSX and design tokens JSON produced here become direct inputs to the executor during the `execute` phase, reducing frontend implementation ambiguity.

package/docs/readmes/features/skills/prepare-next.md

@@ -0,0 +1,109 @@
+# prepare-next
+
+> Produce a clean next-run handoff without auto-loading stale context, unreviewed learnings, or unresolved ambiguities into the next session.
+
+| Property | Value |
+|---|---|
+| **ID** | `prepare-next` |
+| **Type** | Flexible |
+| **Trigger** | After a run or execution slice completes |
+| **Failure mode** | Stale context or unreviewed learnings silently poisoning the next session |
+
+## Purpose
+
+`prepare-next` closes a session cleanly. It captures what happened — completed work, blockers, required approvals, and explicitly accepted learnings — and packages this into a structured handoff that the next session can consume without ambiguity.
+
+The key discipline: it does not auto-apply anything. Proposed learnings, unresolved decisions, and speculative improvements are documented as pending — not silently promoted into the next run's starting assumptions. A poisoned handoff is worse than no handoff at all.
+
+## When to Invoke
+
+- After a run or execution slice completes (all planned work for the session is done or blocked).
+- Before context compaction would cause loss of session state.
+- Before switching from one implementation phase to another.
+- As the final step before disconnecting from a long-running task.
+
+> [!TIP]
+> The `stop_handoff_harvest` hook fires at session end and captures final observability data. `prepare-next` is the skill-level complement — it produces the structured human-readable handoff document that the hook captures.
+
+## When NOT to Invoke
+
+- Mid-task: do not interrupt execution to produce a handoff. Finish the current task unit first (or explicitly note the interruption point).
+- Nothing meaningful has happened: an empty handoff is not useful. If nothing was completed, note what was attempted and why it was blocked.
+
+> [!WARNING]
+> Do not mutate `input/`. The `input/` directory is operator-supplied truth. Handoff documents belong in `docs/plans/` or the state root (`~/.wazir/projects/<project-slug>/`), not in `input/`.
+
+## Phases
+
+1. **Inventory completed work** — what was finished, with verification evidence.
+2. **Inventory blockers** — what could not be completed and why.
+3. **List required approvals** — decisions the operator needs to make before the next run can proceed.
+4. **Identify accepted learnings** — only learnings that have been explicitly reviewed and accepted by the operator go in the handoff. Proposed learnings are listed separately as pending.
+5. **Write the handoff** — using the `templates/artifacts/next-run-handoff.md` structure.
+
+## Input
+
+- Session history: what was planned, what was done, what failed
+- Verification records from `wz:verification`
+- Any blockers or open questions from `wz:debugging`
+- Operator-reviewed learnings only
+
+## Output
+
+One handoff document using the `templates/artifacts/next-run-handoff.md` structure.
+
+### Required Handoff Sections
+
+| Section | Content |
+|---|---|
+| Current status | One-line summary of where the run ended |
+| Completed work | Finished tasks with verification evidence |
+| Unresolved blockers | What is blocking progress and why |
+| Required approvals | Decisions needed from the operator |
+| Accepted learnings | Only explicitly reviewed/approved learnings |
+| Pending review | Proposed learnings or observations awaiting operator review |
+
+## Rules
+
+- Do not mutate `input/`.
+- Do not auto-load proposed or unreviewed learnings into the next run.
+- Do not mark work as complete in the handoff if `wz:verification` has not passed for it.
+
+## Example
+
+**Scenario:** Session ends after completing 3 of 5 plan sections.
+
+```markdown
+# Next-Run Handoff — 2026-03-13
+
+## Current Status
+Completed sections 1-3 of rate-limiting implementation plan. Blocked on section 4 (Redis integration test environment).
+
+## Completed Work
+- Section 1: Redis client setup — VERIFIED (npm test → 3 passing)
+- Section 2: Rate-limit middleware — VERIFIED (npm test → 7 passing)
+- Section 3: Router wiring — VERIFIED (npm test → 12 passing)
+
+## Unresolved Blockers
+- Section 4 requires a Redis test container — CI environment does not have Docker. Options documented in debugging log.
+
+## Required Approvals
+- Operator decision needed: use mock Redis for test environment OR add Docker to CI?
+
+## Accepted Learnings
+(none — operator has not reviewed the proposed learnings below)
+
+## Pending Review
+- Proposed: Redis client should use connection pooling (observed latency spike under load in manual test).
+  Status: PROPOSED — not yet reviewed. Do not apply automatically.
+```
+
+## Integration
+
+`prepare-next` is the terminal step of any execution session:
+
+```
+wz:tdd → wz:verification → prepare-next → [operator reviews] → next session starts clean
+```
+
+The `stop_handoff_harvest` hook captures the handoff document at session end. The `pre_compact_summary` hook summarizes captured state before context compaction — both hooks consume the data that `prepare-next` produces.

package/docs/readmes/features/skills/run-audit.md

@@ -0,0 +1,159 @@
+# run-audit
+
+> Interactive structured codebase audit — security, quality, architecture, performance, dependencies, or custom. Produces a source-backed findings report or actionable fix plan.
+
+| Property | Value |
+|---|---|
+| **ID** | `run-audit` |
+| **Type** | Flexible |
+| **Trigger** | Explicit operator request: "audit this codebase" or `/run-audit` |
+| **Output modes** | Report (findings only) or Plan (findings → implementation tasks) |
+
+## Purpose
+
+`run-audit` runs a disciplined, multi-step audit pipeline on a codebase. It collects three parameters interactively (type, scope, output mode), then executes a research-based analysis using audit-specific expertise modules. Every finding is backed by source citations — no speculation, no summary without evidence.
+
+The audit operates through the `researcher` role composed with `audit-*` expertise modules. No new canonical role is introduced.
+
+## When to Invoke
+
+- Operator requests a security, quality, architecture, performance, or dependency review.
+- Before a major refactor — establish a baseline of known issues.
+- After merging a large feature branch — verify no quality regression.
+- As part of a scheduled review cadence.
+
+> [!WARNING]
+> Pre-flight: the project must be a git repository. If there are uncommitted changes, the agent warns before proceeding — audit accuracy depends on a stable working tree.
+
+## When NOT to Invoke
+
+- You want a self-audit of the Wazir project itself — use `self-audit` instead.
+- You need a quick project overview — use `scan-project` instead.
+- Implementation is already in progress and you need to fix a specific known issue — use `wz:debugging`.
+
+## Phases
+
+### Step 1: Collect Audit Type
+
+Prompts the operator to choose one of six audit types:
+
+| # | Type | Focus |
+|---|---|---|
+| 1 | Security | Vulnerabilities, secrets, OWASP, dependency risks |
+| 2 | Code Quality | Complexity, duplication, dead code, naming |
+| 3 | Architecture | Coupling, layering, design doc adherence |
+| 4 | Performance | Bottlenecks, memory, inefficient patterns |
+| 5 | Dependencies | Outdated, vulnerable, unused packages |
+| 6 | Custom | Operator-described focus |
+
+### Step 2: Collect Scope
+
+| # | Scope | Description |
+|---|---|---|
+| 1 | Whole project | Scan entire codebase |
+| 2 | Specific branch | Diff against base branch |
+| 3 | Specific paths/files | Audit only named directories or files |
+
+### Step 3: Collect Output Mode
+
+| # | Mode | Description |
+|---|---|---|
+| 1 | Report | Structured findings, analysis only |
+| 2 | Plan | Findings become implementation tasks via `wz:writing-plans` |
+
+### Step 4: Confirm and Start
+
+Summarizes parameters, waits for operator confirmation before proceeding.
+
+### Step 5: Research + Audit (Autonomous)
+
+Composes a `researcher` agent with the relevant `audit-*` expertise modules from `expertise/composition-map.yaml`:
+
+| Audit Type | Expertise Module |
+|---|---|
+| Security | `audit-security` |
+| Code Quality | `audit-code-quality` |
+| Architecture | `audit-architecture` |
+| Performance | `audit-performance` |
+| Dependencies | `audit-dependencies` |
+| Custom | All `audit-*` modules combined |
+
+The researcher scans the project, categorizes findings by severity (critical / high / medium / low / info), and produces evidence-backed findings with location (`file:line`), code snippets, and remediation guidance.
+
+### Step 6: Output
+
+**Report mode:** Presents findings directly to the operator. Operator can copy or request a save.
+
+**Plan mode:**
+1. Presents findings for approval.
+2. On approval, saves findings to `docs/plans/YYYY-MM-DD-audit-<type>-findings.md`.
+3. Invokes `wz:writing-plans` to produce an implementation plan from the approved findings.
+
+## Input
+
+- Git repository (required)
+- Operator-selected: type, scope, output mode
+- Audit parameters (passed as context to researcher — not written to `input/`)
+
+## Output
+
+### Report Format
+
+```markdown
+# Security Audit Report — 2026-03-13
+
+## Summary
+- Scope: whole project
+- Total findings: 7 (Critical: 1, High: 2, Medium: 3, Low: 1)
+
+## Findings
+
+### Critical
+
+#### [C-001] Hardcoded JWT secret in source
+- Category: Secrets exposure
+- Location: src/auth/jwt.js:14
+- Evidence: `const secret = "hardcoded-secret-do-not-use";`
+- Remediation: Move to environment variable, rotate the secret
+```
+
+## Example
+
+**Scenario:** Security audit of a Node.js API before a production launch.
+
+```
+Agent: What would you like to audit?
+Operator: 1 (Security)
+
+Agent: What scope?
+Operator: 1 (Whole project)
+
+Agent: What output?
+Operator: 2 (Plan)
+
+Agent: Audit Summary:
+  Type: security | Scope: whole-project | Output: plan
+  Proceed? (y/n)
+Operator: y
+
+[Researcher composes with audit-security expertise]
+[Scans entire codebase]
+[Produces 7 findings]
+
+Agent: Found 7 findings (1 critical, 2 high...). Approve as fix plan basis?
+Operator: y
+
+[Saves to docs/plans/2026-03-13-audit-security-findings.md]
+[Invokes wz:writing-plans]
+[Produces docs/plans/2026-03-13-audit-security-implementation.md]
+```
+
+## Integration
+
+`run-audit` feeds into `wz:writing-plans` in plan mode, completing the loop:
+
+```
+run-audit (findings approved) → wz:writing-plans → wz:tdd → wz:verification
+```
+
+For Wazir self-audits specifically, use `self-audit` instead — it adds worktree isolation and automated fix-verify cycles.

package/docs/readmes/features/skills/scan-project.md

@@ -0,0 +1,109 @@
+# scan-project
+
+> Build an evidence-based project profile from the repo's actual surfaces — before clarification or planning begins.
+
+| Property | Value |
+|---|---|
+| **ID** | `scan-project` |
+| **Type** | Flexible |
+| **Trigger** | `discover` phase start — or any time a project profile is needed |
+| **Failure mode** | Planning from assumptions instead of evidence |
+
+## Purpose
+
+`scan-project` replaces assumption-based project understanding with a minimal, targeted scan of the surfaces that actually describe what a project is and how it works. It answers five specific questions — no more — using manifests, scripts, CI config, and active documentation rather than guesswork.
+
+The output is a concise profile with file references, not a comprehensive audit. It is the starting point for clarification and planning, not an end in itself.
+
+## When to Invoke
+
+- At the start of the `discover` phase.
+- When an operator asks "what kind of project is this?" before making changes.
+- Before `wz:brainstorming` when the codebase is unfamiliar.
+- When returning to a project after a gap and needing to re-establish context.
+
+## When NOT to Invoke
+
+- The project profile is already current and no new surfaces have changed.
+- A deep structural audit is needed — use `run-audit` instead.
+- You are mid-execution and already have a verified project profile — do not re-scan.
+
+> [!TIP]
+> `scan-project` answers "what is this?" — `run-audit` answers "what is wrong with this?". Do not substitute one for the other.
+
+## The Five Questions
+
+This skill answers exactly these five questions:
+
+| Question | Sources to prefer |
+|---|---|
+| What kind of project is this? | `package.json`, `*.manifest.yaml`, `README.md` |
+| Which languages and toolchains are active? | Lock files, CI config, build scripts |
+| How is verification expected to work? | `npm test`, CI pipeline, test runner config |
+| Where are the relevant product and architecture docs? | `docs/`, `ARCHITECTURE.md`, `CONTRIBUTING.md` |
+| What constraints appear in `input/`? | Everything in the `input/` directory |
+
+## Phases
+
+1. **Read `input/`** — operator-supplied constraints and requirements first.
+2. **Read manifests** — `package.json`, `*.yaml` manifests, lock files.
+3. **Read CI config** — `.github/workflows/`, `.circleci/`, `Makefile`, build scripts.
+4. **Read key docs** — `README.md`, `docs/architecture.md` if present.
+5. **Identify verification path** — what command proves the project is working?
+6. **Compile profile** — concise summary with file references and open unknowns.
+
+## Rules
+
+- Prefer manifests, scripts, CI config, and current docs over assumptions.
+- Treat inactive surfaces (dead code, archived docs) as historical context only — do not let them shape the profile.
+- Inspect the **smallest** set of surfaces needed. Depth is `run-audit`'s job.
+
+## Input
+
+- Project repository
+- `input/` directory contents
+
+## Output
+
+| Artifact | Description |
+|---|---|
+| Project profile | Concise summary answering the five questions, with file references |
+| Open unknowns | Things that require research or clarification to resolve |
+
+## Example
+
+**Scenario:** New conversation on a TypeScript API project.
+
+```
+Agent: Invoking scan-project for the discover phase.
+
+Scanning:
+  input/          → found: requirements.md (API endpoints spec)
+  package.json    → TypeScript, Express, Jest, ts-jest
+  .github/        → CI runs npm test on push to main
+  README.md       → "REST API for task management, PostgreSQL backend"
+  docs/           → architecture.md exists, last updated 2026-02-01
+
+Profile:
+  Type:          REST API (Node.js / TypeScript / Express)
+  Languages:     TypeScript (primary)
+  Verification:  npm test (Jest + ts-jest, ~120 tests)
+  Key docs:      docs/architecture.md, README.md
+  Constraints:   input/requirements.md — 5 new endpoints needed, auth via JWT
+
+Open unknowns:
+  - Database migration strategy not documented — needs clarification
+  - No staging environment mentioned in CI — deployment path unknown
+```
+
+This profile feeds directly into `wz:brainstorming` as context for the design phase.
+
+## Integration
+
+`scan-project` is the opening move of the discover phase:
+
+```
+discover: scan-project → wz:brainstorming (design) → wz:writing-plans (plan) → execute
+```
+
+The open unknowns it produces become the clarifying questions for the `clarify` phase, and the verification path it identifies becomes the test command used throughout `wz:tdd` and `wz:verification`.