doit-toolkit-cli 0.1.11__tar.gz

doit_toolkit_cli-0.1.11/.claude/commands/doit.checkin.md

@@ -0,0 +1,363 @@
+---
+description: Finalize feature implementation, close issues, update roadmaps, and create pull request
+---
+
+## 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` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
+
+2. **Load checkin context**:
+   - **REQUIRED**: Read spec.md for feature name and requirements
+   - **REQUIRED**: Read tasks.md for completion status
+   - **IF EXISTS**: Read review-report.md for code review status
+   - **IF EXISTS**: Read test-report.md for test status
+
+3. **Retrieve GitHub issues for feature**:
+   - Detect GitHub remote: `git remote get-url origin`
+   - If GitHub remote found:
+     - Search for Epic issue matching feature branch name
+     - Search for Feature issues linked to the Epic
+     - Search for Task issues linked to Features
+     - Build issue hierarchy tree
+   - If no GitHub remote: Skip issue management, proceed to step 6
+
+4. **Review issue completion status**:
+   - For each issue in hierarchy:
+     - Check if issue is open or closed
+     - Compare against tasks.md completion
+   - Generate status summary:
+
+     ```text
+     ## Issue Status
+
+     ### Epic: #XXX - [Epic Name]
+     Status: OPEN
+
+     ### Features
+     | Issue | Title | Status | Tasks Done |
+     |-------|-------|--------|------------|
+     | #YYY | Feature A | OPEN | 5/5 |
+     | #ZZZ | Feature B | OPEN | 3/4 |
+
+     ### Tasks
+     | Issue | Title | Status |
+     |-------|-------|--------|
+     | #AAA | Task 1 | CLOSED |
+     | #BBB | Task 2 | OPEN |
+     ```
+
+5. **Handle incomplete issues**:
+   - If any issues are still open but tasks show complete:
+     - List the incomplete issues
+     - Ask: "The following issues are still open. Do you want to close them? (yes/no/select)"
+     - If "select": Present each issue for individual decision
+   - If tasks show incomplete work:
+     - Warn: "Some tasks are not marked complete in tasks.md"
+     - Ask: "Do you want to proceed anyway? (yes/no)"
+   - Close approved issues via GitHub API
+
+6. **Update roadmap files** (FR-039, FR-040):
+
+   #### 6.1 Get Current Feature Branch
+
+   ```bash
+   git branch --show-current
+   ```
+
+   Extract the feature pattern (e.g., `008-doit-roadmapit-command` from branch name).
+
+   #### 6.2 Check and Update roadmap.md
+
+   - Check if `.doit/memory/roadmap.md` exists:
+     - If NOT exists: Log "No roadmap.md found, skipping roadmap archive"
+     - If exists:
+       1. Read the roadmap file
+       2. Search for items with matching feature branch reference `[###-feature-name]`
+          - Pattern: Items containing backtick references like `` `008-feature-name` `` or `[008-feature-name]`
+       3. For each matching item found:
+          - Extract: item text, priority (P1-P4), rationale
+          - Remove the item from its current priority section
+          - Mark as completed with `[x]` if using checkbox format
+
+   #### 6.3 Archive to completed_roadmap.md
+
+   - Check if `.doit/memory/completed_roadmap.md` exists:
+     - If NOT exists:
+       1. Copy template from `.doit/templates/completed-roadmap-template.md`
+       2. Replace `[PROJECT_NAME]` with project name
+       3. Replace `[DATE]` with current date
+       4. If template not found, create with basic structure:
+          ```markdown
+          # Completed Roadmap Items
+
+          **Project**: [Project Name]
+          **Created**: [Date]
+
+          ## Recently Completed
+
+          | Item | Original Priority | Completed Date | Feature Branch | Notes |
+          |------|-------------------|----------------|----------------|-------|
+          ```
+     - If exists: Load existing file
+
+   - For each matched roadmap item:
+     1. Add to "Recently Completed" table with:
+        - Item text (without the branch reference)
+        - Original priority (P1-P4)
+        - Completion date (today's date)
+        - Feature branch reference (`` `###-feature-name` ``)
+        - Notes (from spec.md summary if available)
+
+   - **Maintain 20-item limit** in Recently Completed:
+     1. Count items in "Recently Completed" section
+     2. If count > 20:
+        - Move oldest items (beyond 20) to Archive section
+        - Update Statistics section with new counts (P1, P2, P3, P4 totals)
+
+   #### 6.4 Write Updated Files
+
+   - Write updated roadmap.md (with completed items removed)
+   - Write updated completed_roadmap.md (with new completed items)
+
+   #### 6.5 Report Roadmap Changes
+
+   ```markdown
+   ## Roadmap Archive Summary
+
+   **Items Archived**: [N]
+   | Item | Original Priority |
+   |------|-------------------|
+   | [item text] | P[N] |
+
+   **Files Updated**:
+   - `.doit/memory/roadmap.md` - Removed [N] completed items
+   - `.doit/memory/completed_roadmap.md` - Added [N] items to archive
+   ```
+
+   If no matching items found: Log "No matching roadmap items found for branch [branch-name]"
+
+7. **Generate feature documentation** in docs/:
+   - Create `docs/features/[feature-name].md`:
+
+     ```markdown
+     # [Feature Name]
+
+     **Completed**: [date]
+     **Branch**: [branch name]
+     **PR**: #XXX
+
+     ## Overview
+     [Summary from spec.md]
+
+     ## Requirements Implemented
+     | ID | Description | Status |
+     |----|-------------|--------|
+     | FR-001 | ... | Done |
+
+     ## Technical Details
+     [Key decisions from plan.md]
+
+     ## Files Changed
+     [List from tasks.md]
+
+     ## Testing
+     - Automated tests: [summary from test-report.md]
+     - Manual tests: [summary from review-report.md]
+
+     ## Related Issues
+     - Epic: #XXX
+     - Features: #YYY, #ZZZ
+     - Tasks: #AAA, #BBB, ...
+     ```
+
+8. **Prepare git commit**:
+   - Stage all changes: `git add -A`
+   - Generate commit message from feature context:
+
+     ```text
+     feat([feature-name]): [brief description]
+
+     Implements [Epic/Feature name] with the following:
+     - [Key change 1]
+     - [Key change 2]
+     - [Key change 3]
+
+     Closes #XXX, #YYY, #ZZZ
+
+     Requirements: FR-001, FR-002, ...
+     Tests: X passed, Y manual verified
+     ```
+
+   - Execute commit: `git commit -m "[message]"`
+
+9. **Create pull request**:
+   - Determine target branch:
+     - Check $ARGUMENTS for `--target [branch]` flag
+     - If not specified, check for `develop` branch
+     - If no `develop`, use `main` or `master`
+   - Check for gh CLI:
+     - Run `which gh` to verify installation
+     - If not found: Output manual PR instructions and skip (FR-044 fallback)
+   - If gh CLI available:
+     - Push branch: `git push -u origin [branch]`
+     - Create PR:
+
+       ```bash
+       gh pr create \
+         --title "feat([feature]): [description]" \
+         --body "[PR body from template]" \
+         --base [target-branch]
+       ```
+
+   - PR body template:
+
+     ```markdown
+     ## Summary
+     [Brief description from spec.md]
+
+     ## Changes
+     - [List of key changes]
+
+     ## Testing
+     - [ ] Automated tests pass
+     - [ ] Manual testing complete
+     - [ ] Code review approved
+
+     ## Requirements
+     | ID | Description | Status |
+     |----|-------------|--------|
+     | FR-XXX | ... | Done |
+
+     ## Related Issues
+     Closes #XXX, #YYY, #ZZZ
+
+     ---
+     Generated by `/doit.checkin`
+     ```
+
+10. **Handle missing gh CLI** (FR-044 fallback):
+    - If gh CLI not installed:
+
+      ```text
+      ## Manual PR Creation Required
+
+      The gh CLI is not installed. Please create a PR manually:
+
+      1. Push your branch:
+         git push -u origin [branch-name]
+
+      2. Create PR at:
+         https://github.com/[owner]/[repo]/compare/[target]...[branch]
+
+      3. Use this PR template:
+         [output template content]
+
+      4. Link these issues:
+         - Closes #XXX, #YYY, #ZZZ
+      ```
+
+11. **Handle missing develop branch** (fallback):
+    - If target branch doesn't exist:
+      - Check for `main`, then `master`
+      - If none found, ask user for target branch name
+
+12. **Report**: Output summary:
+    - Issues closed (count)
+    - Roadmap updated (yes/no)
+    - Documentation generated (path)
+    - Commit created (hash)
+    - PR created (URL) or manual instructions
+    - Next steps (merge PR, delete branch after merge)
+
+## Key Rules
+
+- Use absolute paths for all file operations
+- Never force-push or modify git history
+- Always confirm before closing issues
+- Generate documentation even if GitHub unavailable
+- Provide manual fallbacks for all GitHub operations
+- Include issue references in commit message for auto-linking
+
+---
+
+## Next Steps
+
+After completing this command, display a recommendation section based on the outcome:
+
+### On Success (PR merged or ready to merge)
+
+Display the following at the end of your output:
+
+```markdown
+---
+
+## Next Steps
+
+┌───────────────────────────────────────────────────────────────────────────────────────┐
+│  Workflow Progress                                                                    │
+│  ● specit → ● planit → ● taskit → ● implementit → ● testit → ● reviewit → ● checkin  │
+└───────────────────────────────────────────────────────────────────────────────────────┘
+
+**Status**: Feature complete! 🎉
+
+**Recommended**: Run `/doit.roadmapit` to update the project roadmap with this completion.
+
+**Alternative**: Run `/doit.specit [next feature]` to start the next feature development.
+```
+
+### On Partial Success (PR created, pending merge)
+
+If the PR was created but not yet merged:
+
+```markdown
+---
+
+## Next Steps
+
+┌───────────────────────────────────────────────────────────────────────────────────────┐
+│  Workflow Progress                                                                    │
+│  ● specit → ● planit → ● taskit → ● implementit → ● testit → ● reviewit → ◐ checkin  │
+└───────────────────────────────────────────────────────────────────────────────────────┘
+
+**Status**: PR created and awaiting merge.
+
+**Next**: Merge the PR when ready, then run `/doit.roadmapit` to update the project roadmap.
+```
+
+### On Error (issues incomplete)
+
+If some issues or tasks are still incomplete:
+
+```markdown
+---
+
+## Next Steps
+
+**Issue**: Some tasks or issues are still open.
+
+**Recommended**: Complete the outstanding tasks with `/doit.implementit`, or use `--force` flag to proceed anyway.
+```

doit_toolkit_cli-0.1.11/.claude/commands/doit.constitution.md

@@ -0,0 +1,187 @@
+---
+description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
+handoffs: 
+  - label: Build Specification
+    agent: doit.doit
+    prompt: Implement the feature specification based on the updated constitution. I want to build...
+---
+
+## 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
+
+You are updating the project constitution at `.doit/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
+
+Follow this execution flow:
+
+1. Load the existing constitution template at `.doit/memory/constitution.md`.
+   - Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
+   **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
+
+2. **Section-by-Section Update Mode**:
+   If user input specifies a particular section to update (e.g., "update tech stack" or "change deployment"), focus on that section only while preserving other sections. Supported section keywords:
+   - "purpose" / "goals" → Purpose & Goals section
+   - "tech" / "stack" / "language" → Tech Stack section
+   - "infrastructure" / "hosting" / "cloud" → Infrastructure section
+   - "deployment" / "ci" / "cd" → Deployment section
+   - "principles" → Core Principles section
+   - "governance" → Governance section
+
+   If no specific section mentioned, proceed with full constitution review.
+
+3. **Guided Prompts for New Placeholders**:
+   When collecting values for the following placeholders, use these prompts if values not provided:
+
+   **Purpose & Goals:**
+   - [PROJECT_PURPOSE]: "What is the main purpose of this project? What problem does it solve?"
+   - [SUCCESS_CRITERIA]: "What are the key success metrics or criteria for this project?"
+
+   **Tech Stack (FR-005, FR-006):**
+   - [PRIMARY_LANGUAGE]: "What programming language(s) will this project use? (e.g., Python 3.11+, TypeScript)"
+   - [FRAMEWORKS]: "What frameworks will you use? (e.g., FastAPI, React, Django)"
+   - [KEY_LIBRARIES]: "What key libraries/packages are essential? (e.g., Pydantic, SQLAlchemy)"
+
+   **Infrastructure (FR-007, FR-008):**
+   - [HOSTING_PLATFORM]: "Where will this be hosted? (e.g., AWS ECS, Google Cloud Run, Vercel, self-hosted)"
+   - [CLOUD_PROVIDER]: "Which cloud provider? (AWS, GCP, Azure, multi-cloud, on-premises)"
+   - [DATABASE]: "What database(s) will you use? (e.g., PostgreSQL, MongoDB, none)"
+
+   **Deployment:**
+   - [CICD_PIPELINE]: "What CI/CD system? (e.g., GitHub Actions, GitLab CI, Jenkins)"
+   - [DEPLOYMENT_STRATEGY]: "What deployment strategy? (blue-green, rolling, canary, manual)"
+   - [ENVIRONMENTS]: "What environments? (e.g., dev, staging, production)"
+
+4. Collect/derive values for placeholders:
+   - If user input (conversation) supplies a value, use it.
+   - Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
+   - For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
+   - `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
+     - MAJOR: Backward incompatible governance/principle removals or redefinitions.
+     - MINOR: New principle/section added or materially expanded guidance.
+     - PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
+   - If version bump type ambiguous, propose reasoning before finalizing.
+
+5. Draft the updated constitution content:
+   - Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
+   - Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
+   - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
+   - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
+
+6. Consistency propagation checklist (convert prior checklist into active validations):
+   - Read `.doit/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
+   - Read `.doit/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
+   - Read `.doit/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
+   - Read each command file in `.doit/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
+   - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.
+
+7. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
+   - Version change: old → new
+   - List of modified principles (old title → new title if renamed)
+   - Added sections
+   - Removed sections
+   - Templates requiring updates (✅ updated / ⚠ pending) with file paths
+   - Follow-up TODOs if any placeholders intentionally deferred.
+
+8. Validation before final output:
+   - No remaining unexplained bracket tokens.
+   - Version line matches report.
+   - Dates ISO format YYYY-MM-DD.
+   - Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
+
+9. Write the completed constitution back to `.doit/memory/constitution.md` (overwrite).
+
+10. Output a final summary to the user with:
+    - New version and bump rationale.
+    - Any files flagged for manual follow-up.
+    - Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).
+
+Formatting & Style Requirements:
+
+- Use Markdown headings exactly as in the template (do not demote/promote levels).
+- Wrap long rationale lines to keep readability (<100 chars ideally) but do not hard enforce with awkward breaks.
+- Keep a single blank line between sections.
+- Avoid trailing whitespace.
+
+If the user supplies partial updates (e.g., only one principle revision), still perform validation and version decision steps.
+
+If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.
+
+Do not create a new template; always operate on the existing `.doit/memory/constitution.md` file.
+
+## Constitution Reading Utility
+
+Other commands can read and utilize the constitution by:
+
+1. **Loading the constitution**: Read `.doit/memory/constitution.md`
+2. **Extracting tech stack**: Parse the Tech Stack section for language, framework, and library information
+3. **Extracting infrastructure**: Parse the Infrastructure section for hosting and cloud provider details
+4. **Extracting deployment**: Parse the Deployment section for CI/CD and environment configuration
+5. **Checking principles**: Parse Core Principles for project constraints and requirements
+
+**Usage in other commands**:
+
+```text
+# At the start of any command that needs project context:
+1. Check if `.doit/memory/constitution.md` exists
+2. If exists, read and parse relevant sections
+3. Use extracted values to inform command behavior (e.g., scaffold uses tech stack, plan uses constraints)
+4. If constitution is incomplete or missing, prompt user or proceed with defaults
+```
+
+---
+
+## Next Steps
+
+After completing this command, display a recommendation section based on the outcome:
+
+### On Success (constitution created or updated)
+
+Display the following at the end of your output:
+
+```markdown
+---
+
+## Next Steps
+
+**Constitution updated successfully!**
+
+**Recommended**: Run `/doit.scaffoldit` to generate project structure based on the tech stack in your constitution.
+
+**Alternative**: Run `/doit.specit [feature description]` to create a feature specification for your first feature.
+```
+
+### On Error (validation failed)
+
+If the constitution could not be validated:
+
+```markdown
+---
+
+## Next Steps
+
+**Issue**: Constitution validation failed.
+
+**Recommended**: Review the errors above and correct the constitution content.
+```