akili-specs 2.1.0

package/.claude/commands/akili-specify.md

@@ -0,0 +1,320 @@
+---
+description: Draft detailed requirements, UI/UX designs, and technical tasks for a proposed feature.
+---
+
+# Generate AKILI-SPECS for Module
+
+Generate a clear Spec-Driven Development document set for one bounded module, feature, bugfix, or enhancement inside `docs/specs/`.
+
+The goal is not to create long documents. The goal is to make the intended behavior, design choices, implementation tasks, and verification path easy to review before code is written.
+
+If `proposal.md` already exists for the same spec path, treat it as the approved intent and convert it into full requirements, design, and tasks. If no proposal exists, create the spec directly from the user's request and repository context.
+
+## Usage
+
+```
+/akili-specify <spec-path>
+```
+
+**Examples:**
+
+- `/akili-specify loan`
+- `/akili-specify enhancements/renewals`
+- `/akili-specify admin/user-management`
+
+## Arguments
+
+- `$ARGUMENTS` — Relative path under `docs/specs/` where the spec should live. It may be a flat module name or a nested taxonomy path.
+
+## Output
+
+Create or update these files under `docs/specs/$ARGUMENTS/`:
+
+- `proposal.md` — optional prior intent document created by `/akili-propose`
+- `requirements.md` — what behavior must exist and why it matters
+- `design.md` — how the behavior will be implemented within the current architecture
+- `tasks.md` — small executable tasks linked to requirements and design sections
+
+Use the lightest useful depth:
+
+| Depth | Use For | Documentation Style |
+|---|---|---|
+| Lite | Small bugfixes, copy updates, narrow UI tweaks | Extreme brevity: 1-2 bullet points for requirements, skip architectural boilerplate, 1 strictly focused task. Output tokens must be minimized. |
+| Standard | Normal features and enhancements | Full requirements, scenarios, design decisions, task breakdown |
+| Full | Risky, cross-cutting, API, data, auth, or migration work | Include alternatives, rollout, risks, observability, rollback |
+
+Lite mode still requires testable requirements, scenarios, and done criteria.
+
+## Behavior
+
+### Step 0: Setup
+
+**Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
+
+1. Create directory `docs/specs/$ARGUMENTS/` if it does not exist.
+2. Read project-level reference context (IN THIS ORDER):
+   - Root `CLAUDE.md`
+   - `AGENTS.md`
+   - `docs/prd.md`
+   - `docs/ux-ui/design.md` (legacy fallback: `docs/system-design/design.md`)
+   - `docs/trd/trd.md` (legacy fallback: `docs/detailed-design/detailed-design.md`)
+   - The constitutional templates in `docs/specs/general-setup/` (`requirements.md`, `design.md`, `task.md`)
+   - Package-level `CLAUDE.md` files if they exist
+3. Read `docs/specs/$ARGUMENTS/proposal.md` if it exists.
+4. Read nearby or dependent specs under `docs/specs/` that overlap with the requested path.
+5. Respect the repository's current package layout and naming conventions instead of assuming a fixed stack.
+6. **CodeGraph over full reads:** If `.codegraph/` exists, use `codegraph_search` and `codegraph_context` to inspect relevant code paths instead of reading full source files or using generic `grep`/`glob`. This drastically reduces input tokens.
+
+---
+
+### Phase 1: Requirements (`requirements.md`)
+
+**Role:** Product Owner — define what is being built and why.
+
+#### Step 1.1 — Explore & Scope Chunking
+
+Use `brainstorming` and, when helpful, `product-manager-toolkit` to clarify:
+
+- user problem and target actors
+- scope boundaries and dependencies
+- primary flows and feature areas
+- success metrics and constraints
+
+**Scope Chunking:** If the user provides a very large instruction or epic, evaluate if it is too massive for a single spec.
+- If it spans multiple distinct modules or features, propose splitting the spec into multiple separate specs.
+- If the user agrees, create the separate folders under `docs/specs/` and draft a `proposal.md` or jump straight to the split documents (`requirements.md`, `design.md`, `tasks.md`) for each chunk.
+
+#### Step 1.2 — Write
+
+Generate `requirements.md` using `docs/specs/general-setup/requirements.md` as the format source.
+
+Minimum content:
+
+1. Document Control
+2. Executive Summary
+3. Glossary
+4. System Context & Scope
+5. Stakeholders / Personas
+6. Functional Requirements
+7. Non-Functional Requirements
+8. Requirement ID Index
+
+Guidelines:
+
+- follow the repo's established requirement ID pattern from `general-setup`
+- align with `docs/prd.md`
+- align with `proposal.md` when present
+- reference existing specs when this work extends another feature
+- use measurable, testable language
+- separate goals from requirements
+- write behavior contracts, not implementation plans
+- **Design Impact:** IF the proposal includes Figma or visual design context, ensure UI states (loading, error, empty, success) and responsive behaviors are captured as explicit requirements.
+- include concrete scenarios for key requirements using `GIVEN`, `WHEN`, `THEN`, and optional `AND`
+- make requirement strength explicit with `SHALL`, `MUST`, `SHOULD`, or `MAY` where useful
+
+Recommended requirement shape:
+
+```markdown
+### Requirement: Short Behavior Name
+
+The system SHALL provide the observable behavior.
+
+#### Scenario: Main case
+
+- GIVEN the relevant starting state
+- WHEN the triggering action happens
+- THEN the expected outcome occurs
+- AND any required side effect is visible
+- BUT it must NOT [explicit constraint or negative path]
+- AND IT MUST [explicit validation or boundary condition]
+```
+
+Avoid putting internal class names, library choices, or step-by-step implementation details in requirements. Those belong in `design.md` or `tasks.md`.
+
+If `proposal.md` includes a Requirement Delta Preview, convert it into full requirements:
+
+- `ADDED` items become new requirements and scenarios
+- `MODIFIED` items become updated behavior descriptions with before/after context
+- `REMOVED` items become explicit deprecation or removal requirements with migration notes when relevant
+
+#### Step 1.3 — Present & Approve
+
+Present a clear summary of the generated requirements on the screen (including the main scenarios, rules, and any explicit negative constraints) so the user can review what was done before deciding.
+
+Then explicitly ask the user how to proceed, providing these options:
+
+1. **Continue** (Proceed to Phase 2: `design.md`)
+2. **Adjust** (Refine or change the requirements)
+3. **Stop** (Pause the specification process here)
+4. **Type something** (Provide custom instructions or feedback)
+
+Wait for the user's response before moving on.
+
+---
+
+### Phase 2: Design (`design.md`)
+
+**Role:** System Architect — define how the feature will be built.
+
+#### Step 2.1 — Explore
+
+Use `brainstorming` to explore trade-offs before writing.
+
+If the work includes meaningful UI/UX impact, use this skill preference:
+
+- `ui-ux-pro-max` if available
+- otherwise `frontend-design` + `stitch-design`
+
+Use additional technical skills as needed:
+
+- `nestjs-expert`
+- `api-design-principles`
+- `shadcn-ui`
+- `tailwind-design-system`
+- `vercel-react-best-practices`
+- `error-handling-patterns`
+- `aws-serverless`
+
+#### Step 2.2 — Write
+
+Generate `design.md` using `docs/specs/general-setup/design.md` as the format source.
+
+Minimum content:
+
+1. Document Control
+2. Executive Summary
+3. Architecture Overview
+4. Extended Directory Structure
+5. Data Model
+6. API Design
+7. Backend Module Design
+8. Frontend / UX Component Architecture
+9. Shared Contracts or Package Extensions
+10. Design Decisions
+
+Guidelines:
+
+- extend existing architecture rather than replacing it
+- use current repo paths and package names
+- include UI/UX decisions when the feature affects screens, flows, or components
+- **Design Impact:** IF the proposal includes Figma or visual design context, break down the visual design into a clear Frontend Component Architecture (e.g., atomic components) and define the necessary Design Tokens (colors, typography).
+- tie design sections back to requirements explicitly
+- record meaningful trade-offs and rejected alternatives for non-trivial decisions
+- call out data, API, security, error-handling, observability, and rollback concerns when relevant
+- keep design decisions practical enough that an implementer can act without re-discovery
+- **Code Suppression:** DO NOT generate code snippets or implementation examples in `design.md`. Design decisions must remain conceptual to conserve output tokens. The actual code will be written during execution.
+
+#### Step 2.3 — Present & Approve
+
+Present a clear summary of the generated design on the screen (including the architecture, data models, API endpoints, and main design decisions) so the user can review what was done before deciding.
+
+Then explicitly ask the user how to proceed, providing these options:
+
+1. **Review Design** (Use the `judgment-day` skill to review the design before moving on)
+2. **Continue** (Proceed to Phase 3: `tasks.md`)
+3. **Adjust** (Refine or change the design)
+4. **Stop** (Pause the specification process here)
+5. **Type something** (Provide custom instructions or feedback)
+
+If the user selects **Review Design** and the `judgment-day` judges detect issues that need correction, present the following options to handle the findings:
+
+1. **Fix and Re-judge** (Apply fixes for the findings and run the judgment again)
+2. **Fix only** (Apply fixes but do not run the judgment again)
+3. **Continue** (Accept the design as-is and proceed to Phase 3: `tasks.md`)
+4. **Stop** (Pause the specification process here)
+5. **Type something** (Provide custom instructions or feedback)
+
+Wait for the user's response before moving on.
+
+---
+
+### Phase 3: Tasks (`tasks.md`)
+
+**Role:** Tech Lead — define the implementation plan.
+
+#### Step 3.1 — Explore
+
+Use `brainstorming` to determine sequencing, dependencies, parallelization, and test strategy.
+
+#### Step 3.2 — Write
+
+Generate `tasks.md` using `docs/specs/general-setup/task.md` as the format source.
+
+Each task should include:
+
+- status
+- size
+- dependencies
+- requirements covered
+- design references
+- scope
+- tests
+- done criteria
+- relevant skills
+
+Skill inventory should use real, available skills only.
+
+Task quality rules:
+
+- one task should be small enough to complete and verify in one focused session
+- every task must reference the requirements it satisfies
+- every task must include a concrete verification command or manual check
+- tasks should explicitly address the negative constraints (`BUT it must NOT`) and strict validations (`AND IT MUST`) defined in their respective requirement scenarios
+- **Design Impact:** IF the proposal includes Figma or visual design context, ensure frontend tasks are atomic, focusing on specific UI components, layouts, styling, and states extracted from the design.
+- tasks should avoid broad instructions like "implement feature" without scoped subtasks
+- tasks may be grouped by phase, but dependencies must remain explicit
+
+Preferred UI/UX skill rule:
+
+- use `ui-ux-pro-max` when available for UI-heavy tasks
+- otherwise use `frontend-design` and/or `stitch-design`
+
+#### Step 3.3 — Present & Approve
+
+Present a clear summary of the generated tasks on the screen, including:
+- A high-level list of the tasks to be implemented so the user understands the plan without reading the full document.
+- An **Estimated Lines of Code (LOC)** output for the entire spec.
+- A **PR Strategy Recommendation**: If the estimate exceeds ~400 LOC or the task graph is highly complex, recommend splitting the implementation into multiple Pull Requests and suggest logical boundaries (e.g., "PR 1: Backend/API, PR 2: Frontend UI").
+
+Then explicitly ask the user how to proceed, providing these options:
+
+1. **Continue** (Proceed to the final Verification Checklist)
+2. **Adjust** (Refine or change the tasks or PR strategy)
+3. **Stop** (Pause the specification process here)
+4. **Type something** (Provide custom instructions or feedback)
+
+Wait for the user's response before moving on.
+
+---
+
+## Verification Checklist
+
+After all three documents are approved, verify:
+
+- [ ] All 3 files exist with non-empty content
+- [ ] All documents follow `docs/specs/general-setup/` conventions
+- [ ] The chosen depth is appropriate for the risk and size of the work
+- [ ] Requirements describe observable behavior, not implementation details
+- [ ] Key requirements include Given/When/Then scenarios with strict `BUT` and `AND IT MUST` rules where applicable
+- [ ] Every requirement appears in at least one task
+- [ ] Every task references requirements and design sections
+- [ ] Every task has clear done criteria and verification guidance that accounts for the negative scenarios
+- [ ] The task dependency graph has no circular dependencies
+- [ ] The spec path matches the repo's chosen taxonomy under `docs/specs/`
+- [ ] Only real, available skills are referenced in tasks
+
+---
+
+## Review Handoff
+
+When the spec is ready, generate a short, easy-to-understand summary (summary facil de entender de lo que se hizo) that reflects what was done. It must include:
+
+1. Spec path and chosen depth: Lite, Standard, or Full
+2. Problem being solved
+3. Requirements and key scenarios
+4. Important design decisions and risks
+5. Task count, estimated LOC, and recommended PR strategy (single vs. multiple PRs)
+6. Recommended first task
+7. Open questions or assumptions that still need user confirmation
+
+If a proposal existed, mention whether the generated spec stayed aligned with it or changed based on implementation discovery.

package/.claude/commands/akili-test.md

@@ -0,0 +1,141 @@
+---
+description: Write and execute comprehensive automated unit/integration tests for the implemented feature.
+---
+
+# Test AKILI-SPECS Implementation
+
+Run automated and, when needed, manual tests against a spec path's implementation. Produce `test-report.md` with results, requirement coverage, scenario traceability, and failures.
+
+Testing should prove the behavior promised in `requirements.md`, not only increase test count.
+
+## Usage
+
+```
+/akili-test <spec-path>
+```
+
+**Examples:**
+
+- `/akili-test loan`
+- `/akili-test enhancements/renewals`
+
+## Arguments
+
+- `$ARGUMENTS` — Relative path under `docs/specs/` that contains `requirements.md`, `design.md`, and `tasks.md`.
+
+## Output
+
+Create or update `docs/specs/$ARGUMENTS/test-report.md` with:
+
+- commands run and their results
+- requirement-to-test matrix
+- scenario coverage status
+- failures and remediation steps
+- accepted gaps with reasons when full automation is not practical
+
+---
+
+## Behavior
+
+### Phase 0: Load Context
+
+**Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
+
+1. Read project-level context (IN THIS ORDER):
+   - root `CLAUDE.md`
+   - `AGENTS.md`
+   - `docs/prd.md`
+   - `docs/ux-ui/design.md` (legacy fallback: `docs/system-design/design.md`)
+   - `docs/trd/trd.md` (legacy fallback: `docs/detailed-design/detailed-design.md`)
+   - Package-level `CLAUDE.md` and `AGENTS.md` files if they exist
+2. Read spec context:
+   - `docs/specs/$ARGUMENTS/requirements.md`
+   - `docs/specs/$ARGUMENTS/design.md`
+   - `docs/specs/$ARGUMENTS/tasks.md`
+3. Identify backend, frontend, and end-to-end scope from the design and tasks.
+4. Extract key requirements, Given/When/Then scenarios, negative constraints (`BUT it must NOT`), and strict validations (`AND IT MUST`) from `requirements.md`.
+
+### Phase 1: Unit Tests
+
+- Create or improve backend unit tests where needed.
+- Create or improve frontend unit tests where needed.
+- Explicitly test negative constraints (`BUT it must NOT`) and strict boundary validations (`AND IT MUST`).
+- Map tests back to requirements and scenarios.
+- Prefer focused tests that prove one behavior clearly over broad tests with unclear intent.
+
+Use skills as needed:
+
+- `nestjs-expert`
+- `systematic-debugging`
+- `vercel-react-best-practices`
+- `react-doctor`
+
+### Phase 2: Integration Tests
+
+- Create or improve API integration tests where relevant.
+- Validate auth, request/response shape, and major flows.
+- Cover cross-module behavior that cannot be proven by unit tests alone.
+
+### Phase 3: End-to-End Tests
+
+- Create or improve E2E tests for user-visible workflows.
+- If the work is UI-heavy, prefer `ui-ux-pro-max` when available.
+- Otherwise use `frontend-design` and the UX/UI design doc as the UX reference.
+- Use E2E tests for critical user journeys, not every small component state.
+
+### Phase 4: Coverage & Traceability
+
+Create a requirement-to-test matrix so every key requirement has test evidence or an explicit gap. Ensure negative constraints and strict validations are mapped.
+
+Recommended matrix columns:
+
+| Requirement | Scenario | Test Type | Test File or Command | Result | Gap or Notes |
+|---|---|---|---|---|---|
+
+### Phase 5: Generate Test Report
+
+Create `docs/specs/$ARGUMENTS/test-report.md`.
+
+**Automated Test Parsing Option:** If the repository uses standard testing frameworks (like Jest or Vitest) and has a AKILI test parsing helper installed (e.g. `akili/scripts/parse_tests.js`), you may run the tests outputting to JSON (e.g. `jest --json --outputFile=jest-results.json` or `vitest --reporter=json --outputFile=test-results.json`) and run:
+`node <path-to-akili>/scripts/parse_tests.js jest-results.json`
+to automatically scaffold the results matrix directly into the test report sections.
+
+The report must include:
+
+1. Document Control
+2. Summary
+3. Backend Unit Tests
+4. Frontend Unit Tests
+5. Integration Tests
+6. E2E Tests
+7. Coverage & Traceability
+8. Remediation
+9. Accepted Gaps, if any
+
+### Phase 6: Report to User
+
+Generate a short, easy-to-understand summary (summary facil de entender de lo que se hizo) of the overall test status, test counts, requirement coverage, scenario gaps, and top failures. If failures exist, ask whether to fix failures, add missing tests, fix all, or keep only the report.
+
+---
+
+## UX Testing Guidance
+
+When a spec includes meaningful UI/UX behavior, verify more than raw functionality:
+
+- flow clarity
+- responsive behavior
+- state transitions
+- accessibility basics
+- visual consistency with `docs/ux-ui/design.md`
+
+If `ui-ux-pro-max` is unavailable, use `frontend-design` plus the UX/UI design document as the fallback reference.
+
+---
+
+## Testing Rules
+
+- Do not mark a requirement covered just because related code exists.
+- Do not hide missing coverage; record it as an explicit gap with remediation.
+- Prefer repository-specific test commands over hardcoded framework assumptions.
+- If a test is flaky, record the flake and avoid treating it as passing evidence until stabilized.
+- If no automated test is practical, document the manual verification steps and why automation was deferred.

package/.claude/commands/akili-validate.md

@@ -0,0 +1,176 @@
+---
+description: Validate that the implemented feature strictly matches all requirements, design tokens, and user flows.
+---
+
+# Validate AKILI-SPECS Implementation
+
+Validate that a spec path's implementation matches its AKILI-SPECS documents. Produce `validation-report.md` with pass, warning, fail, and remediation details.
+
+Validation is the final conformance audit. It checks whether the implementation still matches the approved requirements, scenarios, design decisions, tasks, tests, and constitutional baseline.
+
+> **Recommended model tier:** T3 Auditor (deep independent review). Ensure you are using a strong reasoning model that differs from the one used during implementation.
+
+## Usage
+
+```
+/akili-validate <spec-path>
+```
+
+**Examples:**
+
+- `/akili-validate loan`
+- `/akili-validate enhancements/renewals`
+
+## Arguments
+
+- `$ARGUMENTS` — Relative path under `docs/specs/` containing `requirements.md`, `design.md`, `tasks.md`, and optionally `execution.md`.
+
+## Output
+
+Create or update `docs/specs/$ARGUMENTS/validation-report.md`.
+
+Validation should produce a clear recommendation for whether the spec can be archived with `/akili-archive $ARGUMENTS`.
+
+Use these result levels consistently:
+
+| Result | Meaning |
+|---|---|
+| PASS | The implementation satisfies the requirement, task, or check with evidence |
+| WARN | The implementation is acceptable but has risk, missing evidence, or minor drift |
+| FAIL | The implementation does not satisfy the requirement, task, or check |
+| BLOCKED | Validation could not complete because required context, tooling, or access is missing |
+
+---
+
+## Behavior
+
+### Phase 0: Load Context
+
+**Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
+
+1. Read constitutional context (IN THIS ORDER):
+   - root `CLAUDE.md`
+   - `AGENTS.md`
+   - `docs/prd.md`
+   - `docs/ux-ui/design.md` (legacy fallback: `docs/system-design/design.md`)
+   - `docs/trd/trd.md` (legacy fallback: `docs/detailed-design/detailed-design.md`)
+   - `docs/specs/general-setup/`
+   - package-level `CLAUDE.md` files if they exist
+2. Read spec context:
+   - `docs/specs/$ARGUMENTS/proposal.md` if present
+   - `docs/specs/$ARGUMENTS/requirements.md`
+   - `docs/specs/$ARGUMENTS/design.md`
+   - `docs/specs/$ARGUMENTS/tasks.md`
+   - `docs/specs/$ARGUMENTS/execution.md` if present
+
+### Phase 1: Task Completion Check
+
+Verify task status coverage and report PASS, WARN, or FAIL per task.
+
+Check that completed tasks include execution notes and verification evidence.
+
+### Phase 2: File Existence Check
+
+Parse the design file tree and verify expected new, modified, and deleted files.
+
+### Phase 3: Build Integrity
+
+Run the project's relevant build, type-check, and lint commands.
+
+Prefer the commands defined by the repo rather than assuming a fixed stack.
+
+If no command exists, record the gap and recommend the smallest useful command to add.
+
+### Phase 4: Requirement Coverage Verification
+
+For every requirement in `requirements.md`, verify:
+
+1. it appears in at least one task
+2. mapped tasks are complete when full implementation is claimed
+3. code evidence exists
+4. key scenarios have automated or documented manual test evidence
+5. negative constraints (`BUT it must NOT`) and strict validations (`AND IT MUST`) have been explicitly implemented and verified
+6. behavior matches the requirement intent, not only the task wording
+
+### Phase 5: Quality Audit
+
+Use skills as needed:
+
+- `nestjs-expert`
+- `react-doctor`
+- `api-design-principles`
+- `tailwind-design-system`
+- `frontend-design`
+- `ui-ux-pro-max` if available for UX/UI-heavy validation
+- `systematic-debugging` when failures or inconsistencies appear
+
+Check for:
+
+- architecture compliance
+- API quality
+- frontend quality
+- design-system compliance
+- UX consistency with the UX/UI design document
+- error handling and observability where relevant
+- accessibility and responsive behavior for UI work
+- security and authorization boundaries for protected flows
+
+### Phase 6: Design Conformance
+
+Compare the implementation against the module design and the constitutional docs where relevant.
+
+If the implementation intentionally differs from the design, verify that the design or execution notes explain the change. Otherwise mark the drift as WARN or FAIL depending on risk.
+
+If `proposal.md` exists, also verify that final behavior remains aligned with the approved intent, scope, non-goals, and success criteria.
+
+### Phase 7: Generate Validation Report
+
+Create `docs/specs/$ARGUMENTS/validation-report.md`.
+
+The report must include:
+
+1. Document Control
+2. Summary
+3. Task Completion
+4. File Existence
+5. Build Integrity
+6. Requirement Coverage
+7. Linting & Code Quality
+8. Design Conformance
+9. Test Evidence Summary
+10. Remediation
+11. Archive Readiness Recommendation
+
+The report title must be `# Validation Report — {Spec Name}`.
+
+### Phase 8: Report to User
+
+Generate a short, easy-to-understand summary (summary facil de entender de lo que se hizo) of the overall status, key findings, remediation count, and archive readiness. If issues exist, ask whether to fix all, fix critical only, or keep only the report. If the work is archive-ready, show the exact next command:
+
+```text
+/akili-archive $ARGUMENTS
+```
+
+---
+
+## Error Handling
+
+- If AKILI-SPECS documents are missing, report the missing files and stop.
+- If build fails, continue other checks when possible.
+- If a skill is unavailable, fall back to the next documented skill and note it in the report.
+- If no tasks are complete, still allow partial validation but make the incompleteness explicit.
+- If implementation evidence is inconclusive, mark WARN or BLOCKED instead of guessing.
+- If validation finds spec drift, recommend whether to update the spec, update implementation, or split follow-up work.
+
+---
+
+## Archive Readiness Guidance
+
+The work is ready to consider complete when:
+
+- all required tasks are `[x]`
+- no FAIL findings remain unresolved
+- WARN findings are accepted or have follow-up tasks
+- tests cover the key requirements and scenarios
+- implementation drift is reflected in the AKILI-SPECS docs or execution notes
+- the user has reviewed the validation summary