@dtlabs/ai-toolkit 0.1.2

package/docs/procedures/assessment-approval-gate.md

@@ -0,0 +1,60 @@
+# Procedure: Assessment Remediation Gate
+
+After intervention documents are generated, present findings to the user and obtain explicit approval before any remediation code is written.
+
+## Gate presentation
+
+```
+📊 Assessment Complete — ASSESS-001
+═══════════════════════════════════════
+Assessment results:
+  Generic quality:     [KPI summary scores]
+  Layer violations:    N CRITICAL, N HIGH, N MEDIUM
+  Concurrency hazards: N CRITICAL, N HIGH
+  [other assessments]
+
+Interventions proposed: N total
+  CRITICAL: N  (immediate attention)
+  HIGH:     N  (next sprint)
+  MEDIUM:   N  (planned cycle)
+  LOW:      N  (backlog)
+
+Interventions Index: docs/assessments/ASSESS-001/ASSESS-001-Interventions-Index.md
+```
+
+Use `AskUserQuestion`:
+- **"Approve all"** — all proposed interventions approved
+- **"Approve CRITICAL only"** — only CRITICAL severity approved
+- **"Select interventions"** — user specifies INT-NNN to approve (comma-separated)
+- **"Assessment only"** — stop here, no remediation
+
+If the user selects **"Assessment only"**, skip to the Summary phase.
+
+## Approvals file format
+
+Write `{PREFIX}-Approvals.md` in the assessment directory:
+
+```markdown
+# Approval Record — {PREFIX}
+
+## Assessment Approvals
+
+| Document | Status | Date | Notes |
+|----------|--------|------|-------|
+| {PREFIX}-Generic-Assessment.md | ✅ Reviewed | {date} | — |
+| {PREFIX}-Interventions-Index.md | ✅ Reviewed | {date} | — |
+
+## Remediation Scope
+
+| Intervention | Approved | Date | Notes |
+|---|---|---|---|
+| INT-001 — sql-injection-hardening | ✅ Approved | {date} | — |
+| INT-002 — god-class-decomposition | ✅ Approved | {date} | — |
+| INT-003 — di-refactoring | ❌ Deferred | {date} | Out of current sprint scope |
+```
+
+## Rules
+
+- **Never skip this gate** — remediation cannot start without explicit approval
+- **Log the approval outcome** in the process log
+- **Record every decision** including deferred interventions and the reason

package/docs/procedures/code-generation.md

@@ -0,0 +1,48 @@
+# Code Generation Procedure
+
+Step-by-step workflow for generating or modifying production code.
+
+## When to use
+
+Before writing any new code or modifying existing code. This ensures pattern compliance and avoids introducing inconsistencies.
+
+## Steps
+
+### 1. Read conventions
+
+- Read `AGENTS.md` in the project root — understand tech stack, patterns, constraints
+- If ADR files are referenced, read those too (they contain implementation guardrails)
+- Note the build/verify commands
+
+### 2. Search for existing patterns
+
+- Before writing new code, search the codebase for similar implementations
+- Find at least one existing file that does something similar to your task
+- Match its structure, imports, naming, and style exactly
+- If no similar code exists, follow the patterns described in AGENTS.md
+
+### 3. Write code
+
+- Write in small, focused units — one function, one class, one component at a time
+- Follow the conventions from Step 1 precisely — no creative deviations
+- Use existing utilities, helpers, and abstractions rather than creating new ones
+- Name things consistently with the existing codebase
+
+### 4. Verify compilation
+
+- Run the build/type-check command defined in AGENTS.md
+- Fix any errors or warnings before proceeding
+- If you introduced a new file, verify it's properly imported/registered
+
+### 5. Communicate assumptions
+
+- If you made any assumptions during implementation, state them explicitly
+- If you deviated from the spec for a technical reason, explain why
+- If you identified potential issues or future work, note them
+
+## Anti-patterns
+
+- Writing code without first reading existing patterns
+- Introducing new abstractions when existing ones work
+- Guessing at business logic when the spec is ambiguous (ask instead)
+- Skipping the verification step

package/docs/procedures/code-review.md

@@ -0,0 +1,63 @@
+# Code Review Procedure
+
+Process for reviewing code or preparing a pull request.
+
+## When to use
+
+Before committing code, when reviewing a PR, or when the architect review agent runs.
+
+## Steps
+
+### 1. Understand the change
+
+- Read the diff (or the files in scope)
+- Understand what the change is trying to accomplish
+- Cross-reference with the Tech-Spec or task description if available
+
+### 2. Verify convention adherence
+
+- Read `AGENTS.md` — check every rule against the change
+- Pay special attention to:
+  - Directory structure and file naming
+  - Import/export patterns
+  - Styling approach (no forbidden CSS patterns)
+  - Responsive design requirements
+  - i18n completeness (all locale files updated)
+  - Type safety (no `any`, proper nullability)
+  - Authorization patterns (all endpoints/pages protected)
+
+### 3. Apply checklists
+
+**General checklist (all projects):**
+- [ ] No hardcoded secrets, tokens, or API keys
+- [ ] No `console.log` or debug statements left in
+- [ ] Error handling is present and meaningful
+- [ ] Loading/empty states handled
+- [ ] No unused imports or dead code
+- [ ] Types/interfaces match between layers (DTO ↔ frontend interface)
+
+**Project-specific checklist:**
+- Derive from AGENTS.md's constraints and "do NOT" list
+- Check any ADR guardrails that apply
+
+### 4. Report findings
+
+For each issue, provide:
+- Severity: CRITICAL / WARNING / INFO
+- Location: file path + line number
+- Description: what's wrong
+- Fix suggestion: what to do about it
+
+## PR Description Template
+
+When preparing a PR:
+
+```
+## Summary
+- [1-3 bullet points describing what changed and why]
+
+## Test plan
+- [ ] Build/type-check passes
+- [ ] [Specific test scenarios for this change]
+- [ ] No regressions in related features
+```

package/docs/procedures/effort-estimation.md

@@ -0,0 +1,86 @@
+# Procedure: Effort Estimation
+
+Write `{PREFIX}-Effort-Estimate.md` in the feature directory after Work Breakdown is generated (before the WB approval gate). Append actuals at the end of the pipeline.
+
+## Estimate template
+
+```markdown
+# Effort Estimate — {PREFIX} — {Feature Title}
+
+| Metric | Value |
+|--------|-------|
+| User Stories | N (US-01 ÷ US-NN) |
+| Total tasks | N (DB:N, BE:N, FE:N, INFRA:N, TEST:N) |
+| Implementation phases | N |
+| Human estimate | ~Nh (sequential, no parallelism) |
+| Agent estimate | ~Nh Nmin (parallel dispatch, critical path only) |
+
+## Domain breakdown
+
+| Domain | Tasks | Notes |
+|--------|-------|-------|
+| DB | N | ... |
+| BE | N | ... |
+| FE | N | ... |
+| INFRA | N | ... |
+| TEST | N | ... |
+
+## Implementation phases
+
+| Phase | Tasks | Parallelism |
+|-------|-------|-------------|
+| Phase 1 — {name} | N tasks | N agents in parallel |
+| Phase 2 — {name} | N tasks | N agents in parallel |
+
+## Notes
+
+Estimation assumptions (average task duration, agent concurrency limits, etc.).
+```
+
+## Estimation rules
+
+- **Human estimate**: sum all task durations sequentially. Complexity: simple=2h, medium=4h, complex=8h
+- **Agent estimate**: critical path only — max task duration per phase, summed across phases (parallel dispatch within phase)
+
+## Actuals template (appended at pipeline end)
+
+```markdown
+---
+
+## Actuals vs Estimate
+
+| Metric | Estimated | Actual | Delta |
+|--------|-----------|--------|-------|
+| Total wall-clock (agent) | ~Xh Ymin | Xh Ymin | ±Zmin |
+| Phase 1 — {name} | ~Xmin | Xmin | ±Zmin |
+| Phase 2 — {name} | ~Xmin | Xmin | ±Zmin |
+
+## Task-level actuals
+
+| Task ID | Domain | Agent estimate | Actual | Delta |
+|---------|--------|---------------|--------|-------|
+| INFRA-T01 | INFRA | ~Xmin | Ymin | ±Zmin |
+| US-01-T01 | BE | ~Xmin | Ymin | ±Zmin |
+
+## Estimation accuracy
+
+| Category | Tasks | Avg delta | Trend |
+|----------|-------|-----------|-------|
+| DB | N | ±Xmin | over/under/on-target |
+| BE | N | ±Xmin | over/under/on-target |
+| FE | N | ±Xmin | over/under/on-target |
+| INFRA | N | ±Xmin | over/under/on-target |
+| TEST | N | ±Xmin | over/under/on-target |
+
+## Notes
+
+Which tasks took longer than expected and why.
+```
+
+## Actuals rules
+
+- Round times to the nearest minute
+- Delta: negative = faster than estimated, positive = slower
+- Trend: over-target if avg delta > +15%, under-target if < -15%, otherwise on-target
+- Include total time across all rework attempts for reworked tasks
+- If the process log has gaps, note them and exclude affected tasks from accuracy stats

package/docs/procedures/feature-registry.md

@@ -0,0 +1,50 @@
+# Procedure: Feature Registry
+
+`docs/features/REGISTRY.md` is a cross-feature index maintained by the Project Manager.
+
+## Entry format
+
+```markdown
+## {PREFIX} — {Title}
+**Keywords:** keyword1, keyword2, keyword3, ...
+**Status:** in-progress | completed
+**Summary:** 4–5 lines. What was built, which entities/endpoints were introduced,
+which shared infrastructure was added (e.g. auth middleware, base components),
+and any constraints or decisions that affect future features.
+→ [Detail]({PREFIX}-{slug}/feature.md)
+```
+
+## File structure
+
+```markdown
+# Feature Registry
+
+This file is maintained automatically by the Project Manager.
+Each entry summarises a feature for cross-reference by future features.
+
+---
+
+## FTR-001 — ...
+...
+
+---
+
+## FTR-002 — ...
+...
+```
+
+## Cross-reference analysis
+
+When starting a new feature, check each registry entry for:
+- **OVERLAP** — same domain, entities, or user flows
+- **DEPENDENCY** — requires something delivered by an existing feature
+- **CONFLICT** — contradicts existing business rules or data models
+
+Show findings to the user before executing the plan. If conflicts are found, use `AskUserQuestion` before continuing.
+
+## Rules
+
+- **Max 5 lines for Summary** — brevity is the point
+- **Keywords must be specific** — avoid generic terms like "feature", "user", "data"
+- **Append-only** — never delete existing entries; only update `Status` from `in-progress` to `completed`
+- **Set Status to `completed`** when the PR is successfully created

package/docs/procedures/issues-register.md

@@ -0,0 +1,24 @@
+# Procedure: Issues Register
+
+The Issues Register tracks all non-CRITICAL review findings throughout implementation.
+
+**File**: `{PREFIX}-Issues.md` in the same directory as `feature.md`.
+
+## Format
+
+```markdown
+# Issues Register — {PREFIX}
+
+| # | Severity | US / Scope | File(s) | Description | Status | Resolved by |
+|---|----------|-----------|---------|-------------|--------|-------------|
+| 1 | WARNING | US-01 | file.tsx:45 | Description | OPEN | — |
+| 2 | INFO | US-02 | file.tsx | Description | OPEN | — |
+```
+
+## Rules
+
+- **CRITICAL findings** are NOT tracked here — they trigger immediate rework during US review
+- **WARNING and INFO findings** are logged here and do NOT block the current phase
+- Every review pass appends new findings — never delete rows
+- Final statuses after remediation: `FIXED`, `DEFERRED`
+- The register is the input for the Remediation phase

package/docs/procedures/process-log.md

@@ -0,0 +1,28 @@
+# Procedure: Process Log
+
+The Project Manager maintains `{PREFIX}-process-log.txt` in the same directory as `feature.md`.
+
+## Rules
+
+- **Create or append** at the start of every run — never overwrite previous runs
+- **Log every significant event** with an ISO timestamp
+- **Token tracking**: after every agent call, extract `subagent_tokens` and `duration_ms` from the `<usage>` block. Log immediately and accumulate in an internal token ledger keyed by `agent-name + scope`
+
+## Format
+
+```
+════════════════════════════════════════════════════════
+RUN STARTED — 2026-06-12T09:01:23
+Feature: FTR-001 — [Feature Title]
+════════════════════════════════════════════════════════
+[2026-06-12T09:01:23] Discovery complete — N agents found, prefix: FTR-001
+[2026-06-12T09:01:24] State: FTR-001-Requirements.md (fresh), FTR-001-Tech-Spec.md (missing)
+[2026-06-12T09:01:25] Agent START: generate-tech-spec (FTR-001)
+[2026-06-12T09:03:41] Agent DONE:  generate-tech-spec (FTR-001) — tokens: 21330, duration: 3m 28s
+[2026-06-12T09:03:42] Agent START: validate-feature-docs (FTR-001)
+[2026-06-12T09:05:10] Agent DONE:  validate-feature-docs (FTR-001) — tokens: 9210, duration: 1m 54s
+[2026-06-12T09:05:11] APPROVAL REQUESTED
+[2026-06-12T09:06:02] APPROVAL GRANTED by user
+[2026-06-12T09:08:15] RUN COMPLETE
+════════════════════════════════════════════════════════
+```

package/docs/procedures/secure-coding.md

@@ -0,0 +1,50 @@
+# Secure Coding Procedure
+
+Security checklist for modifying authentication, authorization, or sensitive data handling.
+
+## When to use
+
+When modifying code that handles: authentication, authorization, user input, tokens, secrets, file uploads, or external API calls.
+
+## Checklist
+
+### Authentication & Authorization
+
+- [ ] All endpoints/pages require authentication (unless explicitly public)
+- [ ] Authorization checks are performed server-side, not just in UI
+- [ ] Role/permission checks use the project's authorization framework (from AGENTS.md)
+- [ ] No endpoint allows privilege escalation
+
+### Secrets & Tokens
+
+- [ ] No secrets hardcoded in source (use environment variables or secret managers)
+- [ ] Tokens are never logged, even at debug level
+- [ ] Tokens are stored securely (follow project's token storage approach from AGENTS.md)
+- [ ] Token validation is performed server-side on every request
+
+### Input Validation
+
+- [ ] All user input is validated at the boundary (controller/endpoint level)
+- [ ] Validation uses the project's validation framework (from AGENTS.md)
+- [ ] No SQL injection vectors (use parameterized queries or ORM)
+- [ ] No XSS vectors (no unsafe HTML rendering, sanitize user content)
+- [ ] No command injection (no unsanitized input in shell commands)
+
+### API Security
+
+- [ ] CORS is configured restrictively (only allowed origins)
+- [ ] Rate limiting is considered for public-facing endpoints
+- [ ] Error responses don't leak internal details (stack traces, SQL errors)
+- [ ] File uploads validate size, type, and content
+
+### Data Protection
+
+- [ ] PII is not logged
+- [ ] Sensitive data is not exposed in API responses beyond what's needed
+- [ ] Database queries don't over-fetch (select only needed fields)
+
+## Response to violations
+
+- If you find a security issue in existing code while implementing a feature: note it in the Issues Register as a WARNING
+- If your own code introduces a security issue: fix it immediately before proceeding
+- When in doubt about a security decision: ask the user, don't guess

package/docs/procedures/testing.md

@@ -0,0 +1,63 @@
+# Testing Procedure
+
+Strategy and guidelines for writing and validating tests.
+
+## When to use
+
+When adding tests to the project, either as part of a feature implementation or as standalone test coverage improvement.
+
+## Steps
+
+### 1. Identify what to test
+
+Prioritized test targets:
+1. **Business logic** — core domain operations, calculations, state transitions
+2. **Security** — authorization checks, input validation
+3. **Edge cases** — null/empty inputs, boundaries, error conditions
+4. **API contracts** — request/response shapes, status codes
+5. **Integration points** — database operations, external API calls
+
+### 2. Determine test type
+
+| Type | When | Characteristics |
+|------|------|-----------------|
+| Unit | Isolated logic, pure functions, services | Fast, no I/O, mocked dependencies |
+| Integration | Multi-layer operations, DB queries | Real (or in-memory) DB, slower |
+| API/Controller | HTTP endpoint behavior | Full request pipeline, auth headers |
+| Component | UI component rendering and interaction | DOM rendering, user events |
+
+### 3. Check test infrastructure
+
+- Read existing tests to understand the established patterns
+- Check for test helpers, fixtures, and factories already available
+- Use the project's test framework and libraries (defined in AGENTS.md)
+
+### 4. Write tests
+
+- **Naming**: describe the scenario and expected outcome (e.g., `CreateUser_WithInvalidEmail_Returns422`)
+- **AAA pattern**: Arrange (setup), Act (execute), Assert (verify)
+- **One logical assertion per test** — test one behavior at a time
+- **Isolation**: each test creates its own state, never depends on others
+- **Readability**: a test should be understandable without reading the implementation
+
+### 5. Verify
+
+- Run the test command from AGENTS.md
+- All tests must pass (new and existing)
+- Check for flaky tests (tests that sometimes pass, sometimes fail)
+
+## What NOT to test
+
+- Framework/library behavior (e.g., "does the ORM save correctly?")
+- Trivial code (getters, setters, data classes)
+- Static configuration
+- Third-party code behavior
+- Implementation details that may change during refactoring
+
+## Anti-patterns
+
+- Testing implementation instead of behavior
+- Tests that break when internal code is refactored
+- Tests with hidden dependencies (shared state, execution order)
+- Overly specific mocks that mirror the implementation
+- Missing edge case coverage for the happy path

package/docs/procedures/token-estimation.md

@@ -0,0 +1,123 @@
+# Procedure: Token Estimation
+
+Write `{PREFIX}-Token-Estimate.md` in the feature directory after Work Breakdown is generated. Doc-gen agent actuals are filled in immediately (they have already completed). Implementation agent actuals are filled in at pipeline end. The orchestrator row is appended by the `/implement-feature` skill.
+
+## Estimation model
+
+| Parameter | Value |
+|-----------|-------|
+| Avg chars per token | 4 |
+| Agent system prompt weight — haiku | ~2,000 tokens |
+| Agent system prompt weight — sonnet | ~3,000 tokens |
+| Base overhead per agent call | ~5,000 tokens |
+
+## Cost estimation
+
+Read pricing data from `docs/pricing.md`. Use the **Blended unit cost reference** table for the model in use.
+
+Cost formula per agent call:
+```
+cost ($) = tokens × blended_cost_per_token
+         = tokens × (input_price × 0.80 + output_price × 0.20) / 1,000,000
+```
+
+The 80/20 input/output split is defined in `docs/pricing.md` — update there if the ratio changes.
+
+## Input token estimation per agent type
+
+- **Doc-gen agents**: system prompt + files to read (bytes ÷ 4) + base overhead
+- **Developer agents**: tech-spec section + WB task size + relevant codebase files + base overhead
+- **Review agents**: all files modified in the US scope + base overhead; output ≈ 1,500 tokens fixed
+- **Orchestrator**: sum of all child result sizes (as input) + process log writes (as output) + base overhead
+- **Rework contingency**: add 1 extra developer + 1 review per US (30% rework probability)
+
+## Estimate template
+
+```markdown
+# Token Estimate — {PREFIX} — {Feature Title}
+
+> Estimates computed before execution. Doc-gen actuals filled on completion of each agent.
+> Implementation actuals filled at pipeline end. Orchestrator row added by /implement-feature.
+> Pricing model: docs/pricing.md (80% input / 20% output split).
+
+## Estimation model
+
+| Parameter | Value |
+|-----------|-------|
+| Avg chars per token | 4 |
+| Haiku system prompt | ~2,000 tokens |
+| Sonnet system prompt | ~3,000 tokens |
+| Base overhead per call | ~5,000 tokens |
+| Input/output split | 80% / 20% |
+
+## Agent token estimates and early actuals
+
+| Agent | Model | Est. tokens | Est. cost ($) | Actual tokens | Actual cost ($) | Status |
+|-------|-------|------------|--------------|---------------|----------------|--------|
+| generate-requirements | haiku | N | $N.NNNN | N (actual) | $N.NNNN | ✅ complete |
+| generate-tech-spec | haiku | N | $N.NNNN | N (actual) | $N.NNNN | ✅ complete |
+| validate-feature-docs | haiku | N | $N.NNNN | N (actual) | $N.NNNN | ✅ complete |
+| generate-work-breakdown | haiku | N | $N.NNNN | N (actual) | $N.NNNN | ✅ complete |
+| developer-backend (×N) | sonnet | N | $N.NNNN | — | — | ⏳ pending |
+| developer-frontend (×N) | sonnet | N | $N.NNNN | — | — | ⏳ pending |
+| developer-testing (×N) | sonnet | N | $N.NNNN | — | — | ⏳ pending |
+| review-solution (×N) | sonnet | N | $N.NNNN | — | — | ⏳ pending |
+| project-manager (orchestrator) | sonnet | N | $N.NNNN | — | — | ⏳ pending |
+
+## Phase subtotals
+
+| Phase | Est. tokens | Est. cost ($) | Actual tokens | Actual cost ($) |
+|-------|------------|--------------|---------------|----------------|
+| Doc generation | N | $N.NNNN | N (actual) | $N.NNNN |
+| Phase 1 — {name} | N | $N.NNNN | ⏳ pending | ⏳ pending |
+
+## Grand total
+
+| Metric | Estimated | Actual |
+|--------|-----------|--------|
+| Total tokens | N | partial — updated at pipeline end |
+| Total cost ($) | $N.NN | partial — updated at pipeline end |
+```
+
+## Actuals template (appended at pipeline end)
+
+```markdown
+---
+
+## Actuals vs Estimate
+
+| Agent | Task / Scope | Model | Est. tokens | Actual tokens | Delta | Est. cost ($) | Actual cost ($) | Duration |
+|-------|-------------|-------|------------|---------------|-------|--------------|----------------|----------|
+| generate-requirements | {PREFIX} | haiku | N | N | ±N | $N.NNNN | $N.NNNN | Xmin |
+| generate-tech-spec | {PREFIX} | haiku | N | N | ±N | $N.NNNN | $N.NNNN | Xmin |
+| validate-feature-docs | {PREFIX} | haiku | N | N | ±N | $N.NNNN | $N.NNNN | Xmin |
+| generate-work-breakdown | {PREFIX} | haiku | N | N | ±N | $N.NNNN | $N.NNNN | Xmin |
+| developer-backend | US-01-T01, T02 | sonnet | N | N | ±N | $N.NNNN | $N.NNNN | Xmin |
+| review-solution | US-01 | sonnet | N | N | ±N | $N.NNNN | $N.NNNN | Xmin |
+| project-manager (orchestrator) | — | sonnet | N | N | ±N | $N.NNNN | $N.NNNN | Xh Ymin |
+
+## Estimation accuracy by agent type
+
+| Agent type | Invocations | Avg est. tokens | Avg actual tokens | Avg delta | Trend |
+|-----------|------------|----------------|------------------|-----------|-------|
+| haiku agents | N | N | N | ±N | over/under/on-target |
+| sonnet agents | N | N | N | ±N | over/under/on-target |
+
+## Grand Total
+
+| Metric | Estimated | Actual | Delta |
+|--------|-----------|--------|-------|
+| Total tokens (all agents) | N | N | ±N |
+| Total cost ($) | $N.NN | $N.NN | ±$N.NN |
+| Total wall-clock | Xh Ymin | Xh Ymin | ±Zmin |
+```
+
+## Actuals rules
+
+- One row per invocation — rework invocations get a "(rework)" suffix
+- Delta (tokens): negative = fewer tokens than estimated, positive = more
+- Cost: computed with blended formula from `docs/pricing.md`; use 4 decimal places for per-agent rows, 2 decimal places for totals
+- Trend: over-target if avg delta > +20%, under-target if < -20%, otherwise on-target
+- Duration: convert `duration_ms` to minutes/seconds
+- Model: read from agent frontmatter, default to `sonnet` if not set
+- Missing `<usage>` block → write `N/A`, exclude from accuracy stats and cost totals