doit-toolkit-cli 0.1.9__py3-none-any.whl

doit_cli/templates/commands/doit.reviewit.md

@@ -0,0 +1,355 @@
+---
+description: Review implemented code for quality and completeness against specifications
+handoffs:
+  - label: Run Tests
+    agent: doit.test
+    prompt: Execute automated tests and generate test report
+    send: true
+  - label: Check In
+    agent: doit.checkin
+    prompt: Finalize feature and create pull request
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Load Project Context
+
+Before proceeding, load the project context to inform your responses:
+
+```bash
+doit context show
+```
+
+**If the command fails or doit is not installed**: Continue without context, but note that alignment with project principles cannot be verified.
+
+**Use loaded context to**:
+
+- Reference constitution principles when making decisions
+- Consider roadmap priorities
+- Identify connections to related specifications
+
+## Outline
+
+1. **Setup**: Run `.doit/scripts/bash/check-prerequisites.sh --json --require-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
+
+2. **Load review context**:
+   - **REQUIRED**: Read spec.md for requirements and acceptance criteria
+   - **REQUIRED**: Read plan.md for technical decisions and architecture
+   - **REQUIRED**: Read tasks.md for implementation details and file paths
+   - **IF EXISTS**: Read data-model.md for entity definitions
+   - **IF EXISTS**: Read contracts/ for API specifications
+
+3. **Detect implemented files** from tasks.md:
+   - Parse completed tasks (marked with [X])
+   - Extract file paths from task descriptions
+   - Build list of files to review
+   - Group files by category: models, services, endpoints, tests, config
+
+4. **Execute code review** against requirements:
+   - For each implemented file:
+     - Read file contents
+     - Compare against relevant spec requirements
+     - Check adherence to plan.md architecture decisions
+     - Verify data model compliance (if data-model.md exists)
+     - Verify API contract compliance (if contracts/ exists)
+   - Generate findings with severity levels:
+     - **CRITICAL**: Requirement not implemented, security issue, data loss risk
+     - **MAJOR**: Partial implementation, performance concern, missing validation
+     - **MINOR**: Code style, documentation gap, minor deviation from plan
+     - **INFO**: Suggestion, optimization opportunity, best practice note
+
+5. **Format findings report**:
+
+   ```text
+   ## Code Review Findings
+
+   ### Critical (X findings)
+   | File | Issue | Requirement |
+   |------|-------|-------------|
+   | path/to/file.py | Description | FR-XXX |
+
+   ### Major (X findings)
+   ...
+
+   ### Minor (X findings)
+   ...
+
+   ### Info (X findings)
+   ...
+
+   ### Summary
+   - Total files reviewed: X
+   - Critical issues: X
+   - Major issues: X
+   - Minor issues: X
+   - Recommendations: [list]
+   ```
+
+6. **Extract manual test items** from spec.md:
+   - Parse acceptance criteria/scenarios from spec
+   - Extract testable items that require manual verification
+   - Items typically marked as "Given/When/Then" or acceptance criteria
+   - Create sequential test list with:
+     - Test ID (MT-001, MT-002, etc.)
+     - Description
+     - Expected outcome
+     - Prerequisites (if any)
+
+7. **Present manual tests sequentially**:
+   - For each manual test:
+
+     ```text
+     ## Manual Test MT-XXX
+
+     **Description**: [test description]
+     **Prerequisites**: [any setup needed]
+     **Steps**:
+     1. [step 1]
+     2. [step 2]
+     ...
+
+     **Expected Result**: [what should happen]
+
+     ---
+     Please execute this test and respond with:
+     - PASS: Test passed as expected
+     - FAIL: Test failed (describe what happened)
+     - SKIP: Cannot test right now (provide reason)
+     - BLOCK: Blocked by issue (describe blocker)
+     ```
+
+   - Wait for user response before proceeding to next test
+   - Track results in memory
+
+8. **Track test progress**:
+   - Maintain running tally:
+
+     ```text
+     Progress: X/Y tests completed
+     - Passed: X
+     - Failed: X
+     - Skipped: X
+     - Blocked: X
+     ```
+
+   - Display after each test completion
+
+9. **Collect sign-off**:
+   - After all manual tests complete, present summary:
+
+     ```text
+     ## Manual Testing Complete
+
+     | Test ID | Description | Result |
+     |---------|-------------|--------|
+     | MT-001 | ... | PASS |
+     | MT-002 | ... | FAIL |
+     ...
+
+     **Overall Status**: [PASS if no failures, FAIL otherwise]
+
+     Do you approve these results and sign off on manual testing? (yes/no)
+     ```
+
+   - Record sign-off response and timestamp
+
+10. **Generate review-report.md** in FEATURE_DIR:
+
+    ```markdown
+    # Review Report: [Feature Name]
+
+    **Date**: [timestamp]
+    **Reviewer**: [Claude]
+    **Branch**: [current branch]
+
+    ## Code Review Summary
+
+    | Severity | Count |
+    |----------|-------|
+    | Critical | X |
+    | Major | X |
+    | Minor | X |
+    | Info | X |
+
+    ### Critical Findings
+    [detailed list]
+
+    ### Major Findings
+    [detailed list]
+
+    ## Manual Testing Summary
+
+    | Metric | Count |
+    |--------|-------|
+    | Total Tests | X |
+    | Passed | X |
+    | Failed | X |
+    | Skipped | X |
+    | Blocked | X |
+
+    ### Test Results
+    [detailed table]
+
+    ## Sign-Off
+
+    - Manual Testing: [Approved/Not Approved] at [timestamp]
+    - Notes: [any notes from sign-off]
+
+    ## Recommendations
+
+    1. [recommendation 1]
+    2. [recommendation 2]
+    ...
+
+    ## Next Steps
+
+    - Run `/doit.testit` for automated test execution
+    - Address any CRITICAL or MAJOR findings before merge
+    ```
+
+11. **Generate Mermaid Visualizations** (FR-011, FR-012):
+
+    After collecting all review data, generate visual quality dashboards:
+
+    a. **Finding Distribution Pie Chart**:
+       - Count findings by severity (Critical, Major, Minor, Info)
+       - Generate pie chart showing distribution
+       - Add to review-report.md in Quality Overview section
+
+       ```mermaid
+       pie title Finding Distribution
+           "Critical" : 0
+           "Major" : 2
+           "Minor" : 5
+           "Info" : 3
+       ```
+
+       Insert using auto-generated markers:
+
+       ~~~markdown
+       ## Quality Overview
+
+       <!-- BEGIN:AUTO-GENERATED section="finding-distribution" -->
+       ```mermaid
+       pie title Finding Distribution
+           "Critical" : [count]
+           "Major" : [count]
+           "Minor" : [count]
+           "Info" : [count]
+       ```
+       <!-- END:AUTO-GENERATED -->
+       ~~~
+
+    b. **Test Results Visualization**:
+       - Count test results by status (Passed, Failed, Skipped, Blocked)
+       - Generate pie chart showing test outcomes
+       - Add to review-report.md in Manual Testing Summary section
+
+       ```mermaid
+       pie title Test Results
+           "Passed" : 8
+           "Failed" : 1
+           "Skipped" : 2
+           "Blocked" : 0
+       ```
+
+       Insert using auto-generated markers:
+
+       ~~~markdown
+       ## Test Results Overview
+
+       <!-- BEGIN:AUTO-GENERATED section="test-results" -->
+       ```mermaid
+       pie title Test Results
+           "Passed" : [count]
+           "Failed" : [count]
+           "Skipped" : [count]
+           "Blocked" : [count]
+       ```
+       <!-- END:AUTO-GENERATED -->
+       ~~~
+
+    c. **Conditional Generation**:
+       - If no findings: Show "No Issues Found" message instead of empty pie chart
+       - If no manual tests: Omit Test Results visualization entirely
+       - If all tests pass: Use green-themed success message
+
+    d. **Diagram Validation**:
+       - Verify mermaid syntax is valid
+       - Ensure all counts are non-negative integers
+       - Check that pie chart values sum to total count
+
+12. **Report**: Output path to review-report.md and summary of findings
+
+## Key Rules
+
+- Use absolute paths for all file operations
+- STOP on any CRITICAL finding that blocks further review
+- Present manual tests one at a time, wait for response
+- Generate review-report.md even if some tests are skipped
+- Include timestamps for audit trail
+
+---
+
+## Next Steps
+
+After completing this command, display a recommendation section based on the outcome:
+
+### On Success (review approved, no critical issues)
+
+Display the following at the end of your output:
+
+```markdown
+---
+
+## Next Steps
+
+┌───────────────────────────────────────────────────────────────────────────────────┐
+│  Workflow Progress                                                                │
+│  ● specit → ● planit → ● taskit → ● implementit → ● testit → ● reviewit → ○ checkin │
+└───────────────────────────────────────────────────────────────────────────────────┘
+
+**Recommended**: Run `/doit.checkin` to finalize and merge your changes.
+```
+
+### On Issues Found (changes requested)
+
+If the review found issues that need to be addressed:
+
+```markdown
+---
+
+## Next Steps
+
+┌───────────────────────────────────────────────────────────────────────────────────┐
+│  Workflow Progress                                                                │
+│  ● specit → ● planit → ● taskit → ● implementit → ● testit → ◐ reviewit → ○ checkin │
+└───────────────────────────────────────────────────────────────────────────────────┘
+
+**Status**: [N] critical, [M] major issues found.
+
+**Recommended**: Run `/doit.implementit` to address the review feedback.
+
+After fixing issues, run `/doit.reviewit` again to verify.
+```
+
+### On Error (missing prerequisites)
+
+If required files are missing:
+
+```markdown
+---
+
+## Next Steps
+
+**Issue**: Required files for review are missing.
+
+**Recommended**: Run `/doit.implementit` to complete the implementation first.
+```

doit_cli/templates/commands/doit.roadmapit.md

@@ -0,0 +1,368 @@
+---
+description: Create or update the project roadmap with prioritized requirements, deferred functionality, and AI-suggested enhancements.
+handoffs:
+  - label: Create Specification
+    agent: doit.specit
+    prompt: Create a feature specification for the top roadmap item...
+  - label: Update Constitution
+    agent: doit.constitution
+    prompt: Update the project constitution based on roadmap priorities...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Load Project Context
+
+Before proceeding, load the project context to inform your responses:
+
+```bash
+doit context show
+```
+
+**If the command fails or doit is not installed**: Continue without context, but note that alignment with project principles cannot be verified.
+
+**Use loaded context to**:
+
+- Reference constitution principles when making decisions
+- Consider roadmap priorities
+- Identify connections to related specifications
+
+## Outline
+
+This command creates or updates the project roadmap at `.doit/memory/roadmap.md`. The roadmap captures high-level requirements prioritized by business value, deferred items, and project vision.
+
+### 1. Parse Command Arguments
+
+Extract the operation and details from `$ARGUMENTS`:
+
+| Pattern | Operation | Example |
+|---------|-----------|---------|
+| `create [vision]` | Create new roadmap | `/doit.roadmapit create a task management app` |
+| `add [item]` | Add item to roadmap | `/doit.roadmapit add user authentication` |
+| `defer [item]` | Move item to deferred | `/doit.roadmapit defer social login` |
+| `reprioritize` | Review and change priorities | `/doit.roadmapit reprioritize` |
+| (empty or `update`) | Interactive update | `/doit.roadmapit` |
+
+If no arguments provided or unrecognized pattern, proceed to step 2 for detection.
+
+### 2. Check for Existing Roadmap
+
+Check if `.doit/memory/roadmap.md` exists:
+
+- **If NOT exists**: Proceed to Step 3 (Create Workflow)
+- **If exists**: Proceed to Step 4 (Update Workflow)
+
+### 3. Create Workflow (New Roadmap)
+
+#### 3.1 Ensure Directory Exists
+
+```bash
+mkdir -p .doit/memory
+```
+
+#### 3.2 Gather Project Context
+
+Read these files if they exist to understand project context:
+
+- `.doit/memory/constitution.md` - Project principles and tech stack
+- `README.md` - Project description
+- `package.json` or `pyproject.toml` - Project metadata
+
+#### 3.3 Ask Clarifying Questions
+
+Present questions to establish roadmap foundation. Use the user's input (if provided) as context:
+
+**Question 1: Project Vision**
+> What is the primary goal or vision for this project?
+>
+> Based on your input "[USER_INPUT]", I understand the project is about [INTERPRETATION].
+>
+> Please confirm or provide a more detailed vision statement.
+
+**Question 2: Initial Priority Items**
+> What are the most critical features or requirements for your MVP?
+>
+> Suggested based on your description:
+> - [SUGGESTION_1]
+> - [SUGGESTION_2]
+>
+> Which of these are correct? What would you add or change?
+
+**Question 3: Known Constraints**
+> Are there any constraints or limitations to consider?
+>
+> Options:
+> A. Timeline constraints (specific deadline)
+> B. Technical constraints (must use specific tech)
+> C. Resource constraints (limited team/budget)
+> D. No significant constraints
+> E. Custom (please specify)
+
+#### 3.4 Build Roadmap Structure
+
+Using the gathered information, create the roadmap:
+
+1. Load template from `.doit/templates/roadmap-template.md`
+2. Replace `[PROJECT_NAME]` with project name from constitution or package metadata
+3. Replace `[DATE]` with current date
+4. Replace `[PROJECT_VISION]` with the confirmed vision statement
+5. Populate priority sections based on user's answers:
+   - Add confirmed critical items to P1
+   - Add important but not blocking items to P2
+   - Add nice-to-have items to P3/P4
+6. Leave Deferred Items empty for new roadmaps
+
+#### 3.5 Write Roadmap
+
+Write the populated roadmap to `.doit/memory/roadmap.md`
+
+#### 3.6 Offer Enhancement Suggestions
+
+After creating the roadmap, proceed to Step 6 (AI Suggestions).
+
+---
+
+### 4. Update Workflow (Existing Roadmap)
+
+#### 4.1 Load Current Roadmap
+
+Read `.doit/memory/roadmap.md` and parse:
+
+- Current vision statement
+- All items in P1, P2, P3, P4 sections with their status
+- All deferred items
+- Last updated date
+
+#### 4.2 Display Current State
+
+Show the user the current roadmap state:
+
+```markdown
+## Current Roadmap State
+
+**Vision**: [Current vision statement]
+**Last Updated**: [Date]
+
+### Active Items
+| Priority | Item | Feature Branch | Status |
+|----------|------|----------------|--------|
+| P1 | [item] | [branch-ref] | [ ] |
+| P2 | [item] | [branch-ref] | [ ] |
+...
+
+### Deferred Items
+| Item | Original Priority | Reason |
+|------|-------------------|--------|
+...
+```
+
+#### 4.3 Handle Specific Operations
+
+Based on the parsed operation from Step 1:
+
+**Add Operation (`add [item]`)**:
+1. Ask: "What priority should this item have? (P1/P2/P3/P4)"
+2. Ask: "What's the business rationale for this priority?"
+3. Ask: "Is there a feature branch reference? (e.g., `[###-feature-name]`)"
+4. Add the item to the appropriate section
+
+**Defer Operation (`defer [item]`)**:
+1. Search for the item in active sections
+2. If not found: List available items and ask user to select
+3. If found: Ask "What's the reason for deferring?"
+4. Move item to Deferred section with original priority and reason
+
+**Reprioritize Operation (`reprioritize`)**:
+1. List all active items with current priorities
+2. Ask: "Which items need priority changes?"
+3. For each item to change:
+   - Show current priority
+   - Ask for new priority (P1/P2/P3/P4)
+   - Ask for rationale for the change
+4. Update items in their new sections
+
+**Interactive Update (no specific operation)**:
+1. Ask: "What would you like to do?"
+   - A. Add a new item
+   - B. Defer an item
+   - C. Reprioritize items
+   - D. Update the vision statement
+   - E. Mark an item as complete (moves to completed_roadmap.md)
+2. Execute the selected operation
+
+#### 4.4 Preserve Unmodified Content
+
+When updating the roadmap:
+
+- Keep all items not explicitly changed
+- Maintain existing rationales unless updated
+- Preserve feature branch references
+- Update only the `Last Updated` date
+
+#### 4.5 Write Updated Roadmap
+
+Write the modified roadmap back to `.doit/memory/roadmap.md`
+
+#### 4.6 Offer Enhancement Suggestions
+
+After updating, proceed to Step 6 (AI Suggestions).
+
+---
+
+### 5. Handle Edge Cases
+
+#### 5.1 Malformed Roadmap
+
+If existing roadmap cannot be parsed:
+
+1. Create backup: `mv .doit/memory/roadmap.md .doit/memory/roadmap.md.bak`
+2. Notify user: "The existing roadmap appears to be malformed. A backup has been created."
+3. Try to extract any readable content
+4. Offer to create fresh roadmap incorporating salvaged content
+
+#### 5.2 Item Not Found (for defer/update)
+
+If specified item cannot be found:
+
+1. List all current items in a table
+2. Ask user to select from the list or provide exact item text
+3. Use fuzzy matching to suggest closest matches
+
+#### 5.3 Conflicting Priorities
+
+If user assigns multiple P1 items:
+
+1. Show warning: "You have [N] P1 items. P1 should be reserved for truly critical items."
+2. Ask: "Would you like to compare these items to determine which is most critical?"
+3. If yes, present pairwise comparison for each P1 item
+
+---
+
+### 6. AI Enhancement Suggestions
+
+After any create or update operation, analyze the roadmap and project context to suggest enhancements.
+
+#### 6.1 Gather Context
+
+Read additional context if available:
+
+- `.doit/memory/constitution.md` - Project principles
+- `.doit/memory/completed_roadmap.md` - Past completed items
+- Current roadmap items and gaps
+
+#### 6.2 Generate Suggestions
+
+Based on context, generate 2-5 complementary feature suggestions:
+
+```markdown
+## Enhancement Suggestions
+
+Based on your roadmap and project context, here are some features you might consider:
+
+### Suggestion 1: [Feature Name]
+**Rationale**: [Why this complements existing items]
+**Suggested Priority**: P[N]
+**Aligns with**: [Related existing item or principle]
+
+### Suggestion 2: [Feature Name]
+...
+
+---
+
+**Actions**:
+- Type the suggestion number to add it (e.g., "1" or "1, 3")
+- Type "skip" to finish without adding suggestions
+- Type "modify [N]" to customize a suggestion before adding
+```
+
+#### 6.3 Handle Suggestion Response
+
+- If user selects suggestions: Add them to the appropriate priority sections
+- If user modifies: Apply customizations then add
+- If user skips: Complete without changes
+
+---
+
+### 7. Completion Report
+
+Output a summary of changes:
+
+```markdown
+## Roadmap Update Complete
+
+**File**: `.doit/memory/roadmap.md`
+**Operation**: [Create/Add/Defer/Reprioritize]
+**Date**: [Current date]
+
+### Changes Made
+- [List of specific changes]
+
+### Current Statistics
+| Priority | Count |
+|----------|-------|
+| P1 | [N] |
+| P2 | [N] |
+| P3 | [N] |
+| P4 | [N] |
+| Deferred | [N] |
+
+### Next Steps
+- Run `/doit.specit` to create specs for top priority items
+- Run `/doit.roadmapit` again to continue updating
+- Review completed items in `.doit/memory/completed_roadmap.md`
+```
+
+---
+
+## Key Rules
+
+- Always preserve existing content when updating
+- Ask clarifying questions before making changes
+- Provide AI suggestions after every operation
+- Use feature branch references `[###-feature-name]` for traceability
+- Maintain maximum 3-5 P1 items (truly critical only)
+- Back up malformed roadmaps before recreating
+
+---
+
+## Next Steps
+
+After completing this command, display a recommendation section based on the outcome:
+
+### On Success (roadmap created or updated)
+
+Display the following at the end of your output:
+
+```markdown
+---
+
+## Next Steps
+
+**Roadmap updated!**
+
+**Recommended**: Run `/doit.specit [top priority item]` to create a specification for your highest priority feature.
+
+**Alternative**: Run `/doit.roadmapit add [item]` to add more items to the roadmap.
+```
+
+### On Item Added
+
+If a new item was added to the roadmap:
+
+```markdown
+---
+
+## Next Steps
+
+**Item added to roadmap!**
+
+**Recommended**: Run `/doit.specit [item description]` to create a specification for this item.
+
+**Alternative**: Run `/doit.roadmapit reprioritize` to review and adjust priorities.
+```