ai-devkit 0.2.0

package/templates/env/claude/commands/execute-plan.md

@@ -0,0 +1,71 @@
+# Feature Plan Execution Assistant (Claude)
+
+Help me work through a feature plan one task at a time.
+
+## Step 1: Gather Context
+Ask me for:
+- Feature name (kebab-case, e.g., `user-authentication`)
+- Brief feature/branch description
+- Relevant planning doc path (default `docs/ai/planning/feature-{name}.md`)
+- Any supporting design/implementation docs (design, requirements, implementation)
+- Current branch and latest diff summary (`git status -sb`, `git diff --stat`)
+
+## Step 2: Load the Plan
+- Request the planning doc contents or offer commands like:
+  ```bash
+  cat docs/ai/planning/feature-<name>.md
+  ```
+- Parse sections that represent task lists (look for headings + checkboxes `[ ]`, `[x]`).
+- Build an ordered queue of tasks grouped by section (e.g., Foundation, Core Features, Testing).
+
+## Step 3: Present Task Queue
+Show an overview:
+```
+### Task Queue: <Feature Name>
+1. [status] Section • Task title
+2. ...
+```
+Status legend: `todo`, `in-progress`, `done`, `blocked` (based on checkbox/notes if present).
+
+## Step 4: Interactive Task Execution
+For each task in order:
+1. Display the section/context, full bullet text, and any existing notes.
+2. Suggest relevant docs to reference (requirements/design/implementation).
+3. Ask: "Plan for this task?" Offer to outline sub-steps using the design doc.
+4. Prompt to mark status (`done`, `in-progress`, `blocked`, `skipped`) and capture short notes/next steps.
+5. Encourage code/document edits inside Claude; offer commands/snippets when useful.
+6. If blocked, record blocker info and move task to the end or into a "Blocked" list.
+
+## Step 5: Update Planning Doc
+After each status change, generate a Markdown snippet the user can paste back into the planning doc, e.g.:
+```
+- [x] Task: Implement auth service (Notes: finished POST /auth/login, tests added)
+```
+Remind the user to keep the source doc updated.
+
+## Step 6: Check for Newly Discovered Work
+After each section, ask if new tasks were discovered. If yes, capture them in a "New Work" list with status `todo` and include in the summary.
+
+## Step 7: Session Summary
+Produce a summary table:
+```
+### Execution Summary
+- Completed: (list)
+- In Progress: (list + owners/next steps)
+- Blocked: (list + blockers)
+- Skipped / Deferred: (list + rationale)
+- New Tasks: (list)
+```
+
+## Step 8: Next Actions
+Remind the user to:
+- Update `docs/ai/planning/feature-{name}.md` with the new statuses
+- Sync related docs (requirements/design/implementation/testing) if decisions changed
+- Run `check-implementation` to validate changes against design docs
+- Run `writing-test` to produce unit/integration tests targeting 100% coverage
+- Run `update-planning` to reconcile the planning doc with the latest status
+- Run the `code-review` command when ready for final review
+- Run test suites relevant to completed tasks
+
+---
+Let me know when you're ready to start executing the plan. Provide the feature name and planning doc first.

package/templates/env/claude/commands/new-requirement.md

@@ -0,0 +1,127 @@
+I want to add a new feature/requirement. Please guide me through the complete development workflow:
+
+## Step 1: Capture Requirement
+First, ask me:
+- What is the feature name? (e.g., "user-authentication", "payment-integration")
+- What problem does it solve?
+- Who will use it?
+- What are the key user stories?
+
+## Step 2: Create Feature Documentation Structure
+Once I provide the requirement, create the following files (copy the existing template content so sections/frontmatter match exactly):
+- Start from `docs/ai/requirements/README.md` → save as `docs/ai/requirements/feature-{name}.md`
+- Start from `docs/ai/design/README.md` → save as `docs/ai/design/feature-{name}.md`
+- Start from `docs/ai/planning/README.md` → save as `docs/ai/planning/feature-{name}.md`
+- Start from `docs/ai/implementation/README.md` → save as `docs/ai/implementation/feature-{name}.md`
+- Start from `docs/ai/testing/README.md` → save as `docs/ai/testing/feature-{name}.md`
+
+Ensure the YAML frontmatter and section headings remain identical to the templates before filling in feature-specific content.
+
+## Step 3: Requirements Phase
+Help me fill out `docs/ai/requirements/feature-{name}.md`:
+- Clarify the problem statement
+- Define goals and non-goals
+- Write detailed user stories
+- Establish success criteria
+- Identify constraints and assumptions
+- List open questions
+
+## Step 4: Design Phase
+Guide me through `docs/ai/design/feature-{name}.md`:
+- Propose system architecture changes needed
+- Define data models/schema changes
+- Design API endpoints or interfaces
+- Identify components to create/modify
+- Document key design decisions
+- Note security and performance considerations
+
+## Step 5: Planning Phase
+Help me break down work in `docs/ai/planning/feature-{name}.md`:
+- Create task breakdown with subtasks
+- Identify dependencies (on other features, APIs, etc.)
+- Estimate effort for each task
+- Suggest implementation order
+- Identify risks and mitigation strategies
+
+## Step 6: Documentation Review (Chained Commands)
+Once the docs above are drafted, run the following commands to tighten them up:
+- `review-requirements` to validate the requirements doc for completeness and clarity
+- `review-design` to ensure the design doc aligns with requirements and highlights key decisions
+
+(If you are in Cursor, use `/review-requirements` and `/review-design`.)
+
+## Step 7: Implementation Phase (Deferred)
+This command focuses on documentation only. Actual implementation happens later via `execute-plan`.
+For each task in the plan:
+1. Review the task requirements and design
+2. Ask me to confirm I'm starting this task
+3. Guide implementation with reference to design docs
+4. Suggest code structure and patterns
+5. Help with error handling and edge cases
+6. Update `docs/ai/implementation/feature-{name}.md` with notes
+
+## Step 8: Testing Phase
+Guide testing in `docs/ai/testing/feature-{name}.md`:
+- Draft unit test cases with `writing-test`
+- Draft integration test scenarios with `writing-test`
+- Recommend manual testing steps
+- Help write test code
+- Verify all success criteria are testable
+
+## Step 9: Local Testing & Verification
+Guide me through:
+1. Running all tests locally
+2. Manual testing checklist
+3. Reviewing against requirements
+4. Checking design compliance
+5. Preparing for code review (diff summary, list of files, design references)
+
+## Step 10: Local Code Review (Optional but recommended)
+Before pushing, ask me to run the `code-review` command with the modified file list and relevant docs.
+
+## Step 11: Implementation Execution Reminder
+When ready to implement, run `execute-plan` to work through the planning doc tasks interactively. That command will orchestrate implementation, testing, and follow-up documentation.
+
+## Step 12: Create Merge/Pull Request
+Provide the MR/PR description:
+```markdown
+## Feature: [Feature Name]
+
+### Summary
+[Brief description of what this feature does]
+
+### Requirements
+- Documented in: `docs/ai/requirements/feature-{name}.md`
+- Related to: [issue/ticket number if applicable]
+
+### Changes
+- [List key changes]
+- [List new files/components]
+- [List modified files]
+
+### Design
+- Architecture: [Link to design doc section]
+- Key decisions: [Brief summary]
+
+### Testing
+- Unit tests: [coverage/status]
+- Integration tests: [status]
+- Manual testing: ✓ Completed
+- Test documentation: `docs/ai/testing/feature-{name}.md`
+
+### Checklist
+- [ ] Code follows project standards
+- [ ] All tests pass
+- [ ] Documentation updated
+- [ ] No breaking changes (or documented if any)
+- [ ] Ready for review
+```
+
+Then provide the appropriate command:
+- **GitHub**: `gh pr create --title "feat: [feature-name]" --body-file pr-description.md`
+- **GitLab**: `glab mr create --title "feat: [feature-name]" --description "$(cat mr-description.md)"`
+
+---
+
+**Let's start! Tell me about the feature you want to build.**
+

package/templates/env/claude/commands/review-design.md

@@ -0,0 +1,11 @@
+Review the design documentation in docs/ai/design/feature-{name}.md (and the project-level README if relevant). Summarize:
+- Architecture overview (ensure mermaid diagram is present and accurate)
+- Key components and their responsibilities
+- Technology choices and rationale
+- Data models and relationships
+- API/interface contracts (inputs, outputs, auth)
+- Major design decisions and trade-offs
+- Non-functional requirements that must be preserved
+
+Highlight any inconsistencies, missing sections, or diagrams that need updates.
+

package/templates/env/claude/commands/review-requirements.md

@@ -0,0 +1,9 @@
+Please review `docs/ai/requirements/feature-{name}.md` and the project-level template `docs/ai/requirements/README.md` to ensure structure and content alignment. Summarize:
+- Core problem statement and affected users
+- Goals, non-goals, and success criteria
+- Primary user stories & critical flows
+- Constraints, assumptions, open questions
+- Any missing sections or deviations from the template
+
+Identify gaps or contradictions and suggest clarifications.
+

package/templates/env/claude/commands/update-planning.md

@@ -0,0 +1,61 @@
+# Planning Update Assistant (Claude)
+
+Please help me reconcile the current implementation progress with our planning documentation.
+
+## Step 1: Gather Context
+Ask me for:
+- Feature/branch name and brief status
+- Tasks completed since last update
+- Any new tasks discovered
+- Current blockers or risks
+- Relevant planning docs (e.g., `docs/ai/planning/feature-{name}.md`)
+
+## Step 2: Review Planning Doc
+If a planning doc exists:
+- Summarize existing milestones and task breakdowns
+- Note expected sequencing and dependencies
+- Identify outstanding tasks in the plan
+
+## Step 3: Reconcile Progress
+For each planned task:
+- Mark status (done / in progress / blocked / not started)
+- Note actual work completed vs. planned scope
+- Record blockers or changes in approach
+- Identify tasks that were skipped or added
+
+## Step 4: Update Task List
+Help me produce an updated checklist such as:
+```
+### Current Status: [Feature Name]
+
+#### Done
+- [x] Task A - short note on completion or link to commit/pr
+- [x] Task B
+
+#### In Progress
+- [ ] Task C - waiting on [dependency]
+
+#### Blocked
+- [ ] Task D - blocked by [issue/owner]
+
+#### Newly Discovered Work
+- [ ] Task E - reason discovered
+- [ ] Task F - due by [date]
+```
+
+## Step 5: Next Steps & Priorities
+- Suggest the next 2-3 actionable tasks
+- Highlight risky areas needing attention
+- Recommend coordination (design changes, stakeholder sync, etc.)
+- List documentation updates needed
+
+## Step 6: Summary for Planning Doc
+Prepare a summary paragraph to copy into the planning doc, covering:
+- Current state and progress
+- Major risks/blockers
+- Upcoming focus items
+- Any changes to scope or timeline
+
+---
+Let me know when you're ready to begin the planning update.
+

package/templates/env/claude/commands/writing-test.md

@@ -0,0 +1,44 @@
+Review `docs/ai/testing/feature-{name}.md` and ensure it mirrors the base template before writing tests.
+
+## Step 1: Gather Context
+Ask me for:
+- Feature name and branch
+- Summary of what changed (link to design & requirements docs)
+- Target environment (backend, frontend, full-stack)
+- Existing automated test suites (unit, integration, E2E)
+- Any flaky or slow tests to avoid
+
+## Step 2: Analyze Testing Template
+- Identify required sections from `docs/ai/testing/feature-{name}.md` (unit, integration, manual verification, coverage targets)
+- Confirm success criteria and edge cases from requirements & design docs
+- Note any mocks/stubs or fixtures already available
+
+## Step 3: Unit Tests (Aim for 100% coverage)
+For each module/function:
+1. List behavior scenarios (happy path, edge cases, error handling)
+2. Generate concrete test cases with assertions and inputs
+3. Reference existing utilities/mocks to accelerate implementation
+4. Provide pseudocode or actual test snippets
+5. Highlight potential missing branches preventing full coverage
+
+## Step 4: Integration Tests
+1. Identify critical flows that span multiple components/services
+2. Define setup/teardown steps (databases, APIs, queues)
+3. Outline test cases validating interaction boundaries, data contracts, and failure modes
+4. Suggest instrumentation/logging to debug failures
+
+## Step 5: Coverage Strategy
+- Recommend tooling commands (e.g., `npm run test -- --coverage`)
+- Call out files/functions that still need coverage and why
+- Suggest additional tests if coverage <100%
+
+## Step 6: Manual & Exploratory Testing
+- Propose manual test checklist covering UX, accessibility, and error handling
+- Identify exploratory scenarios or chaos/failure injection tests if relevant
+
+## Step 7: Update Documentation & TODOs
+- Summarize which tests were added or still missing
+- Update `docs/ai/testing/feature-{name}.md` sections with links to test files and results
+- Flag follow-up tasks for deferred tests (with owners/dates)
+
+Let me know when you have the latest code changes ready; we'll write tests together until we hit 100% coverage.

package/templates/env/cursor/commands/check-implementation.md

@@ -0,0 +1,21 @@
+Compare the current implementation with the design in docs/ai/design/ and requirements in docs/ai/requirements/. Please follow this structured review:
+
+1. Ask me for:
+   - Feature/branch description
+   - List of modified files
+   - Relevant design doc(s) (feature-specific and/or project-level)
+   - Any known constraints or assumptions
+
+2. For each design doc:
+   - Summarize key architectural decisions and constraints
+   - Highlight components, interfaces, and data flows that must be respected
+
+3. File-by-file comparison:
+   - Confirm implementation matches design intent
+   - Note deviations or missing pieces
+   - Flag logic gaps, edge cases, or security issues
+   - Suggest simplifications or refactors
+   - Identify missing tests or documentation updates
+
+4. Summarize findings with recommended next steps.
+

package/templates/env/cursor/commands/code-review.md

@@ -0,0 +1,81 @@
+# Local Code Review Assistant
+
+You are helping me perform a local code review **before** I push changes. Please follow this structured workflow.
+
+## Step 1: Gather Context
+Ask me for:
+- Brief feature/branch description
+- List of modified files (with optional summaries)
+- Relevant design doc(s) (e.g., `docs/ai/design/feature-{name}.md` or project-level design)
+- Any known constraints or risky areas
+- Any open bugs or TODOs linked to this work
+- Which tests have already been run
+
+If possible, request the latest diff:
+```bash
+git status -sb
+git diff --stat
+```
+
+## Step 2: Understand Design Alignment
+For each provided design doc:
+- Summarize the architectural intent
+- Note critical requirements, patterns, or constraints the design mandates
+
+## Step 3: File-by-File Review
+For every modified file:
+1. Highlight deviations from the referenced design or requirements
+2. Spot potential logic or flow issues and edge cases
+3. Identify redundant or duplicate code
+4. Suggest simplifications or refactors (prefer clarity over cleverness)
+5. Flag security concerns (input validation, secrets, auth, data handling)
+6. Check for performance pitfalls or scalability risks
+7. Ensure error handling, logging, and observability are appropriate
+8. Note any missing comments or docs
+9. Flag missing or outdated tests related to this file
+
+## Step 4: Cross-Cutting Concerns
+- Verify naming consistency and adherence to project conventions
+- Confirm documentation/comments are updated where the behavior changed
+- Identify missing tests (unit, integration, E2E) needed to cover the changes
+- Ensure configuration/migration updates are captured if applicable
+
+## Step 5: Summarize Findings
+Provide results in this structure:
+```
+### Summary
+- Blocking issues: [count]
+- Important follow-ups: [count]
+- Nice-to-have improvements: [count]
+
+### Detailed Notes
+1. **[File or Component]**
+   - Issue/Observation: ...
+   - Impact: (e.g., blocking / important / nice-to-have)
+   - Recommendation: ...
+   - Design reference: [...]
+
+2. ... (repeat per finding)
+
+### Recommended Next Steps
+- [ ] Address blocking issues
+- [ ] Update design/implementation docs if needed
+- [ ] Add/adjust tests:
+      - Unit:
+      - Integration:
+      - E2E:
+- [ ] Rerun local test suite
+- [ ] Re-run code review command after fixes
+```
+
+## Step 6: Final Checklist
+Confirm whether each item is complete (yes/no/needs follow-up):
+- Implementation matches design & requirements
+- No obvious logic or edge-case gaps remain
+- Redundant code removed or justified
+- Security considerations addressed
+- Tests cover new/changed behavior
+- Documentation/design notes updated
+
+---
+Let me know when you're ready to begin the review.

package/templates/env/cursor/commands/execute-plan.md

@@ -0,0 +1,71 @@
+# Feature Plan Execution Assistant
+
+Help me work through a feature plan one task at a time.
+
+## Step 1: Gather Context
+Ask me for:
+- Feature name (kebab-case, e.g., `user-authentication`)
+- Brief feature/branch description
+- Relevant planning doc path (default `docs/ai/planning/feature-{name}.md`)
+- Any supporting design/implementation docs (design, requirements, implementation)
+- Current branch and latest diff summary (`git status -sb`, `git diff --stat`)
+
+## Step 2: Load the Plan
+- Request the planning doc contents or offer commands like:
+  ```bash
+  cat docs/ai/planning/feature-<name>.md
+  ```
+- Parse sections that represent task lists (look for headings + checkboxes `[ ]`, `[x]`).
+- Build an ordered queue of tasks grouped by section (e.g., Foundation, Core Features, Testing).
+
+## Step 3: Present Task Queue
+Show an overview:
+```
+### Task Queue: <Feature Name>
+1. [status] Section • Task title
+2. ...
+```
+Status legend: `todo`, `in-progress`, `done`, `blocked` (based on checkbox/notes if present).
+
+## Step 4: Interactive Task Execution
+For each task in order:
+1. Display the section/context, full bullet text, and any existing notes.
+2. Suggest relevant docs to reference (requirements/design/implementation).
+3. Ask: "Plan for this task?" Offer to outline sub-steps using the design doc.
+4. Prompt to mark status (`done`, `in-progress`, `blocked`, `skipped`) and capture short notes/next steps.
+5. Encourage code/document edits inside Cursor; offer commands/snippets when useful.
+6. If blocked, record blocker info and move task to the end or into a "Blocked" list.
+
+## Step 5: Update Planning Doc
+After each status change, generate a Markdown snippet the user can paste back into the planning doc, e.g.:
+```
+- [x] Task: Implement auth service (Notes: finished POST /auth/login, tests added)
+```
+Remind the user to keep the source doc updated.
+
+## Step 6: Check for Newly Discovered Work
+After each section, ask if new tasks were discovered. If yes, capture them in a "New Work" list with status `todo` and include in the summary.
+
+## Step 7: Session Summary
+Produce a summary table:
+```
+### Execution Summary
+- Completed: (list)
+- In Progress: (list + owners/next steps)
+- Blocked: (list + blockers)
+- Skipped / Deferred: (list + rationale)
+- New Tasks: (list)
+```
+
+## Step 8: Next Actions
+Remind the user to:
+- Update `docs/ai/planning/feature-{name}.md` with the new statuses
+- Sync related docs (requirements/design/implementation/testing) if decisions changed
+- Run `/check-implementation` to validate changes against design docs
+- Run `/writing-test` to produce unit/integration tests targeting 100% coverage
+- Run `/update-planning` to reconcile the planning doc with the latest status
+- Run `/code-review` when ready for final review
+- Run test suites relevant to completed tasks
+
+---
+Let me know when you're ready to start executing the plan. Provide the feature name and planning doc first.

package/templates/env/cursor/commands/new-requirement.md

@@ -0,0 +1,127 @@
+I want to add a new feature/requirement. Please guide me through the complete development workflow:
+
+## Step 1: Capture Requirement
+First, ask me:
+- What is the feature name? (e.g., "user-authentication", "payment-integration")
+- What problem does it solve?
+- Who will use it?
+- What are the key user stories?
+
+## Step 2: Create Feature Documentation Structure
+Once I provide the requirement, create the following files (copy the existing template content so sections/frontmatter match exactly):
+- Start from `docs/ai/requirements/README.md` → save as `docs/ai/requirements/feature-{name}.md`
+- Start from `docs/ai/design/README.md` → save as `docs/ai/design/feature-{name}.md`
+- Start from `docs/ai/planning/README.md` → save as `docs/ai/planning/feature-{name}.md`
+- Start from `docs/ai/implementation/README.md` → save as `docs/ai/implementation/feature-{name}.md`
+- Start from `docs/ai/testing/README.md` → save as `docs/ai/testing/feature-{name}.md`
+
+Ensure the YAML frontmatter and section headings remain identical to the templates before filling in feature-specific content.
+
+## Step 3: Requirements Phase
+Help me fill out `docs/ai/requirements/feature-{name}.md`:
+- Clarify the problem statement
+- Define goals and non-goals
+- Write detailed user stories
+- Establish success criteria
+- Identify constraints and assumptions
+- List open questions
+
+## Step 4: Design Phase
+Guide me through `docs/ai/design/feature-{name}.md`:
+- Propose system architecture changes needed
+- Define data models/schema changes
+- Design API endpoints or interfaces
+- Identify components to create/modify
+- Document key design decisions
+- Note security and performance considerations
+
+## Step 5: Planning Phase
+Help me break down work in `docs/ai/planning/feature-{name}.md`:
+- Create task breakdown with subtasks
+- Identify dependencies (on other features, APIs, etc.)
+- Estimate effort for each task
+- Suggest implementation order
+- Identify risks and mitigation strategies
+
+## Step 6: Documentation Review (Chained Commands)
+Once the docs above are drafted, run the following commands to tighten them up:
+- `/review-requirements` to validate the requirements doc for completeness and clarity
+- `/review-design` to ensure the design doc aligns with requirements and highlights key decisions
+
+(If you are using Claude Code, reference the `review-requirements` and `review-design` commands instead.)
+
+## Step 7: Implementation Phase (Deferred)
+This command focuses on documentation only. Actual implementation happens later via `/execute-plan`.
+For each task in the plan:
+1. Review the task requirements and design
+2. Ask me to confirm I'm starting this task
+3. Guide implementation with reference to design docs
+4. Suggest code structure and patterns
+5. Help with error handling and edge cases
+6. Update `docs/ai/implementation/feature-{name}.md` with notes
+
+## Step 8: Testing Phase
+Guide testing in `docs/ai/testing/feature-{name}.md`:
+- Draft unit test cases with `/writing-test`
+- Draft integration test scenarios with `/writing-test`
+- Recommend manual testing steps
+- Help write test code
+- Verify all success criteria are testable
+
+## Step 9: Local Testing & Verification
+Guide me through:
+1. Running all tests locally
+2. Manual testing checklist
+3. Reviewing against requirements
+4. Checking design compliance
+5. Preparing for code review (diff summary, list of files, design references)
+
+## Step 10: Local Code Review (Optional but recommended)
+Before pushing, ask me to run `/code-review` with the modified file list and relevant docs.
+
+## Step 11: Implementation Execution Reminder
+When ready to implement, run `/execute-plan` to work through the planning doc tasks interactively. That command will orchestrate implementation, testing, and follow-up documentation.
+
+## Step 12: Create Merge/Pull Request
+Provide the MR/PR description:
+```markdown
+## Feature: [Feature Name]
+
+### Summary
+[Brief description of what this feature does]
+
+### Requirements
+- Documented in: `docs/ai/requirements/feature-{name}.md`
+- Related to: [issue/ticket number if applicable]
+
+### Changes
+- [List key changes]
+- [List new files/components]
+- [List modified files]
+
+### Design
+- Architecture: [Link to design doc section]
+- Key decisions: [Brief summary]
+
+### Testing
+- Unit tests: [coverage/status]
+- Integration tests: [status]
+- Manual testing: ✓ Completed
+- Test documentation: `docs/ai/testing/feature-{name}.md`
+
+### Checklist
+- [ ] Code follows project standards
+- [ ] All tests pass
+- [ ] Documentation updated
+- [ ] No breaking changes (or documented if any)
+- [ ] Ready for review
+```
+
+Then provide the appropriate command:
+- **GitHub**: `gh pr create --title "feat: [feature-name]" --body-file pr-description.md`
+- **GitLab**: `glab mr create --title "feat: [feature-name]" --description "$(cat mr-description.md)"`
+
+---
+
+**Let's start! Tell me about the feature you want to build.**
+

package/templates/env/cursor/commands/review-design.md

@@ -0,0 +1,11 @@
+Review the design documentation in docs/ai/design/feature-{name}.md (and the project-level README if relevant). Summarize:
+- Architecture overview (ensure mermaid diagram is present and accurate)
+- Key components and their responsibilities
+- Technology choices and rationale
+- Data models and relationships
+- API/interface contracts (inputs, outputs, auth)
+- Major design decisions and trade-offs
+- Non-functional requirements that must be preserved
+
+Highlight any inconsistencies, missing sections, or diagrams that need updates.
+

package/templates/env/cursor/commands/review-requirements.md

@@ -0,0 +1,9 @@
+Please review `docs/ai/requirements/feature-{name}.md` and the project-level template `docs/ai/requirements/README.md` to ensure structure and content alignment. Summarize:
+- Core problem statement and affected users
+- Goals, non-goals, and success criteria
+- Primary user stories & critical flows
+- Constraints, assumptions, open questions
+- Any missing sections or deviations from the template
+
+Identify gaps or contradictions and suggest clarifications.
+