@amrhas82/agentic-kit 1.7.0 → 1.7.6

package/packages/opencode/command/docs-builder/templates.md

@@ -0,0 +1,572 @@
+# Documentation Templates
+
+Detailed templates for each file in the /docs structure.
+
+## 00-context/vision.md
+
+```markdown
+# Vision
+
+## Problem
+[What problem does this solve? Who feels the pain?]
+
+## Solution
+[How does this product solve it?]
+
+## Target Users
+[Who is this for? Primary/secondary personas]
+
+## Boundaries
+### In Scope
+- [Feature/capability 1]
+- [Feature/capability 2]
+
+### Out of Scope
+- [What we explicitly won't do]
+- [Adjacent problems we're ignoring]
+
+## Success Metrics
+- [Metric 1: how measured]
+- [Metric 2: how measured]
+```
+
+## 00-context/assumptions.md
+
+```markdown
+# Assumptions & Risks
+
+## Technical Assumptions
+- [Assumption 1: e.g., "Users have Python 3.8+"]
+- [Assumption 2: e.g., "API response time < 200ms"]
+
+## Business Assumptions
+- [Assumption 1: e.g., "Users prefer CLI over GUI"]
+- [Assumption 2: e.g., "10K users within 6 months"]
+
+## Known Risks
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| [Risk description] | High/Med/Low | [How we handle it] |
+
+## Open Questions
+- [ ] [Question 1 that needs answering]
+- [ ] [Question 2 that blocks decisions]
+```
+
+## 00-context/system-state.md
+
+```markdown
+# System State
+
+## What's Implemented
+### Core Features
+- [Feature 1] - Status: ✅ Live | 🚧 In Progress | 📋 Planned
+- [Feature 2] - Status: [...]
+
+### Tech Stack
+- Language: [e.g., Python 3.11]
+- Frameworks: [e.g., FastAPI, React]
+- Database: [e.g., PostgreSQL 15]
+- Infrastructure: [e.g., AWS, Docker]
+
+## What's In Progress
+- [Feature/change being worked on]
+- [Expected completion: rough timeframe]
+
+## What's Planned
+- [Next feature to build]
+- [Roadmap item 2]
+
+## Known Issues
+- [Issue 1: description, severity]
+- [Issue 2: description, severity]
+```
+
+## 01-product/prd.md
+
+```markdown
+# Product Requirements Document
+
+## Problem Statement
+[Clear description of problem. 2-3 paragraphs max.]
+
+## User Personas
+### Primary: [Persona Name]
+- **Who**: [Role/description]
+- **Pain**: [Current problem]
+- **Goal**: [What they want to achieve]
+
+### Secondary: [Persona Name]
+[Same structure]
+
+## Features
+### Must Have (P0)
+1. **[Feature name]**
+   - Description: [What it does]
+   - User value: [Why it matters]
+   - Acceptance: [How we know it's done]
+
+### Should Have (P1)
+[Same structure]
+
+### Nice to Have (P2)
+[Same structure]
+
+## Non-Functional Requirements
+- Performance: [e.g., "API responds < 200ms p95"]
+- Security: [e.g., "OAuth2, encrypted at rest"]
+- Scalability: [e.g., "Handle 10K concurrent users"]
+- Reliability: [e.g., "99.9% uptime"]
+
+## Success Criteria
+- [ ] [Measurable criterion 1]
+- [ ] [Measurable criterion 2]
+
+## Out of Scope
+- [Explicitly excluded feature 1]
+- [Explicitly excluded feature 2]
+```
+
+## 02-features/feature-<name>/feature-spec.md
+
+```markdown
+# Feature: [Name]
+
+## User Intent
+**As a** [user type]
+**I want to** [action]
+**So that** [benefit]
+
+## User Stories
+1. **Story 1**: [Description]
+   - Acceptance: User can [specific action]
+   - Acceptance: System responds with [expected behavior]
+
+## Acceptance Criteria
+- [ ] [Criterion 1: testable condition]
+- [ ] [Criterion 2: testable condition]
+- [ ] [Criterion 3: testable condition]
+
+## Edge Cases
+- **Case 1**: [Scenario] → [Expected behavior]
+- **Case 2**: [Scenario] → [Expected behavior]
+
+## UI/UX Notes
+[Wireframes, mockups, or interaction descriptions]
+```
+
+## 02-features/feature-<name>/tech-design.md
+
+```markdown
+# Technical Design: [Feature Name]
+
+## Architecture Approach
+[High-level approach. Diagram if helpful.]
+
+## Components
+### [Component 1]
+- **Responsibility**: [What it does]
+- **Interface**: [API/methods]
+- **Dependencies**: [What it needs]
+
+### [Component 2]
+[Same structure]
+
+## Data Models
+```language
+[Schema/types/interfaces]
+```
+
+## APIs
+### Endpoint: `METHOD /path`
+- **Request**: [Schema]
+- **Response**: [Schema]
+- **Errors**: [Error codes]
+
+## Security Considerations
+- [Auth/authz requirements]
+- [Data validation]
+- [Potential vulnerabilities addressed]
+
+## Performance Considerations
+- [Expected load]
+- [Optimization strategy]
+- [Caching approach]
+
+## Trade-offs
+- **Decision**: [What we chose]
+- **Alternatives**: [What we didn't choose]
+- **Rationale**: [Why]
+```
+
+## 02-features/feature-<name>/dev-tasks.md
+
+```markdown
+# Development Tasks: [Feature Name]
+
+## Tasks
+- [ ] Task 1: [Specific, executable action]
+  - Dependencies: [What must be done first]
+  - Files: [Which files to touch]
+- [ ] Task 2: [...]
+- [ ] Task 3: [...]
+
+## Implementation Notes
+[Context LLM needs to execute tasks]
+
+## Definition of Done
+- [ ] Code complete
+- [ ] Tests pass
+- [ ] Docs updated
+- [ ] Reviewed
+```
+
+## 02-features/feature-<name>/test-plan.md
+
+```markdown
+# Test Plan: [Feature Name]
+
+## Test Strategy
+- **Unit**: [What to unit test]
+- **Integration**: [What to integration test]
+- **E2E**: [What to E2E test]
+
+## Test Cases
+### TC-1: [Test name]
+- **Given**: [Precondition]
+- **When**: [Action]
+- **Then**: [Expected result]
+
+### TC-2: [Test name]
+[Same structure]
+
+## Edge Cases
+- [ ] Test: [Edge case 1]
+- [ ] Test: [Edge case 2]
+
+## Performance Tests
+- [ ] Load test: [Scenario]
+- [ ] Stress test: [Scenario]
+
+## Security Tests
+- [ ] Auth test: [Scenario]
+- [ ] Input validation: [Scenario]
+```
+
+## 03-logs/implementation-log.md
+
+```markdown
+# Implementation Log
+
+Track what changed in code and why.
+
+## YYYY-MM-DD - [Change Title]
+**What**: [Code changes made - files, functions, modules]
+**Why**: [Business/technical reason for change]
+**Impact**: [What changed for users/devs]
+**Ref**: [PR/commit/issue reference]
+
+---
+
+## YYYY-MM-DD - [Change Title]
+[Repeat structure]
+```
+
+## 03-logs/decisions-log.md
+
+```markdown
+# Decisions Log
+
+Track architectural and product decisions.
+
+## YYYY-MM-DD - [Decision Title]
+**Context**: [Why this decision needed]
+**Options Considered**:
+1. Option A: [Description, pros/cons]
+2. Option B: [Description, pros/cons]
+
+**Decision**: [What we chose]
+**Rationale**: [Why we chose it]
+**Consequences**: [Implications, trade-offs]
+**Ref**: [Discussion link, RFC number]
+
+---
+
+## YYYY-MM-DD - [Decision Title]
+[Repeat structure]
+```
+
+## 03-logs/bug-log.md
+
+```markdown
+# Bug Log
+
+Track bugs, root causes, fixes.
+
+## [BUG-001] - [Bug Title]
+**Reported**: YYYY-MM-DD
+**Severity**: Critical | High | Medium | Low
+**Symptoms**: [What users saw]
+**Root Cause**: [What went wrong technically]
+**Fix**: [How resolved]
+**Prevention**: [How we avoid repeating]
+**Ref**: [Issue/PR reference]
+
+---
+
+## [BUG-002] - [Bug Title]
+[Repeat structure]
+```
+
+## 03-logs/validation-log.md
+
+```markdown
+# Validation Log
+
+Track what happened after shipping.
+
+## YYYY-MM-DD - [Release/Feature Name]
+**Validated**: [What was tested in production]
+**Results**:
+- Metric 1: [Actual vs expected]
+- Metric 2: [Actual vs expected]
+
+**Issues Found**: [Problems discovered post-ship]
+**User Feedback**: [What users said]
+**Next Steps**: [Follow-up actions]
+
+---
+
+## YYYY-MM-DD - [Release/Feature Name]
+[Repeat structure]
+```
+
+## 03-logs/insights.md
+
+```markdown
+# Insights
+
+Learnings and future improvements.
+
+## What Worked Well
+- [Success 1: what and why]
+- [Success 2: what and why]
+
+## What Didn't Work
+- [Issue 1: what went wrong, how to improve]
+- [Issue 2: what went wrong, how to improve]
+
+## Process Improvements
+- [ ] [Change we should make to workflow]
+- [ ] [Tool/practice to adopt]
+
+## Technical Debt
+- [ ] [Debt item 1: what, impact, effort to fix]
+- [ ] [Debt item 2: what, impact, effort to fix]
+
+## Future Optimizations
+- [Optimization opportunity 1]
+- [Optimization opportunity 2]
+```
+
+## 04-process/dev-workflow.md
+
+```markdown
+# Development Workflow
+
+## Daily Dev Loop
+
+### 1. Pick Task
+- Check `02-features/*/dev-tasks.md` or backlog
+- Verify acceptance criteria clear
+
+### 2. Implement
+- Write test first (if TDD)
+- Implement feature
+- Run tests locally
+- Update docs
+
+### 3. Review
+- Self-review checklist:
+  - [ ] Tests pass
+  - [ ] Docs updated
+  - [ ] No console.logs/debugs
+  - [ ] Security reviewed
+- Create PR
+
+### 4. Ship
+- Merge after approval
+- Update `03-logs/implementation-log.md`
+- Monitor production
+
+## Branch Strategy
+- `main`: production-ready code
+- `feature/*`: new features
+- `fix/*`: bug fixes
+
+## Working with LLMs
+- Provide context: link to relevant docs
+- Reference acceptance criteria from feature specs
+- Ask to update logs after changes
+- Request test generation
+
+## Code Review Checklist
+- [ ] Matches acceptance criteria
+- [ ] Tests cover edge cases
+- [ ] Docs updated
+- [ ] No security issues
+- [ ] Performance acceptable
+```
+
+## 04-process/definition-of-done.md
+
+```markdown
+# Definition of Done
+
+## Code Complete
+- [ ] Implements all acceptance criteria
+- [ ] Passes all tests (unit, integration, e2e)
+- [ ] No linter errors
+- [ ] Code reviewed and approved
+- [ ] Security reviewed (if touching auth/data)
+
+## Documentation Complete
+- [ ] Feature spec updated (if behavior changed)
+- [ ] API docs updated (if APIs changed)
+- [ ] README updated (if setup changed)
+- [ ] Logs updated (implementation-log, decisions-log)
+
+## Testing Complete
+- [ ] Unit tests written and passing
+- [ ] Integration tests written and passing
+- [ ] Manual testing completed
+- [ ] Edge cases tested
+- [ ] Performance acceptable
+
+## Release Ready
+- [ ] Deployed to staging
+- [ ] Smoke tests pass
+- [ ] Rollback plan documented
+- [ ] Monitoring in place
+```
+
+## 04-process/llm-prompts.md
+
+```markdown
+# Canonical LLM Prompts
+
+Standard prompts for documentation tasks.
+
+## Create Feature Spec
+\`\`\`
+As backlog-manager, create a feature spec for [feature name] in 02-features/feature-[name]/.
+
+Requirements:
+[Paste requirements]
+
+Include:
+- User stories with acceptance criteria
+- Edge cases
+- UI/UX considerations
+\`\`\`
+
+## Create Technical Design
+\`\`\`
+As architect, create technical design for [feature name] in 02-features/feature-[name]/.
+
+Feature spec: 02-features/feature-[name]/feature-spec.md
+
+Include:
+- Architecture approach
+- Components and data models
+- APIs
+- Security and performance considerations
+- Trade-offs
+\`\`\`
+
+## Generate Dev Tasks
+\`\`\`
+As 2-generate-tasks, break down the feature into executable dev tasks.
+
+Feature spec: 02-features/feature-[name]/feature-spec.md
+Tech design: 02-features/feature-[name]/tech-design.md
+
+Create: 02-features/feature-[name]/dev-tasks.md
+\`\`\`
+
+## Update Implementation Log
+\`\`\`
+Update 03-logs/implementation-log.md with today's changes.
+
+Changes made:
+[Describe changes]
+
+Why:
+[Reason]
+
+Impact:
+[User/developer impact]
+\`\`\`
+
+## Update Decisions Log
+\`\`\`
+Update 03-logs/decisions-log.md with architectural decision.
+
+Decision: [What we decided]
+Context: [Why decision needed]
+Options: [Alternatives considered]
+Rationale: [Why we chose this]
+\`\`\`
+```
+
+## docs/README.md
+
+```markdown
+# Documentation Guide
+
+## Structure
+
+Our docs follow a 5-tier hierarchy:
+
+- **00-context/**: WHY this exists, WHAT's currently built
+- **01-product/**: WHAT we must build (requirements)
+- **02-features/**: HOW features are designed and built
+- **03-logs/**: MEMORY of changes, decisions, bugs over time
+- **04-process/**: HOW to work (workflows, standards)
+
+## Quick Navigation
+
+**Start here**: `00-context/vision.md` - understand product purpose
+**Requirements**: `01-product/prd.md` - single source of truth
+**Feature work**: `02-features/feature-*/` - specs, designs, tasks
+**History**: `03-logs/` - what changed and why
+**Workflows**: `04-process/` - how we work daily
+
+## For Developers
+
+1. **Starting new feature**:
+   - Read: `01-product/prd.md` for requirements
+   - Check: `02-features/` for existing feature patterns
+   - Create: `02-features/feature-<name>/` with 4 files
+
+2. **Daily work**:
+   - Follow: `04-process/dev-workflow.md`
+   - Check: `04-process/definition-of-done.md` before PR
+
+3. **After changes**:
+   - Update: `03-logs/implementation-log.md`
+   - Update: `03-logs/decisions-log.md` if architectural
+
+## For LLMs
+
+Standard prompts: `04-process/llm-prompts.md`
+Context loading: Start with `00-context/`, then drill into specific features
+
+## Legacy Docs
+
+[If existing docs/ subdirs exist, map them here]
+- Old `commands/` → See `02-features/cli/`
+- Old `development/` → See `04-process/dev-workflow.md`
+- Old `guides/` → Distributed across `02-features/`
+- Old `reference/` → See `00-context/` and `01-product/`
+```

package/packages/opencode/command/docs-builder.md

@@ -0,0 +1,106 @@
+---
+name: docs-builder
+description: Create comprehensive project documentation with structured /docs hierarchy
+usage: /docs-builder
+auto_trigger: false
+---
+
+# Documentation Architecture Skill
+
+Create systematic /docs structure following this 5-tier hierarchy:
+
+```
+/docs
+├── 00-context/              # WHY and WHAT EXISTS RIGHT NOW
+├── 01-product/              # WHAT the product must do
+├── 02-features/             # HOW features are designed & built
+├── 03-logs/                 # MEMORY (what changed over time)
+├── 04-process/              # HOW to work with this system
+└── README.md                # Navigation guide
+```
+
+## Workflow
+
+### 1. Discover Project
+- Scan: README, existing /docs, package.json/pyproject.toml, src/, tests/
+- Map existing docs: commands/ → where? development/ → where?
+- Ask: "What's built? What's planned? What's missing?"
+
+### 2. Create Directories
+```bash
+mkdir -p docs/{00-context,01-product,02-features,03-logs,04-process}
+```
+
+### 3. Create Files with TodoWrite
+
+Track progress:
+- [ ] 00-context (3 files: vision.md, assumptions.md, system-state.md)
+- [ ] 01-product (1 file: prd.md)
+- [ ] 02-features (per feature discovered: feature-spec.md, tech-design.md, dev-tasks.md, test-plan.md)
+- [ ] 03-logs (5 files: implementation-log.md, decisions-log.md, bug-log.md, validation-log.md, insights.md)
+- [ ] 04-process (3 files: dev-workflow.md, definition-of-done.md, llm-prompts.md)
+- [ ] docs/README.md
+
+Mark each **completed** before next.
+
+For detailed templates, see: `docs-builder/templates.md`
+
+### 4. Integrate with Existing Docs
+
+**If CLAUDE.md/KNOWLEDGE_BASE.md exist**:
+Update KNOWLEDGE_BASE.md to reference new structure:
+```markdown
+## Project Documentation
+Full /docs structure with context, product, features, logs, process
+→ `docs/README.md`
+```
+
+**If existing /docs subdirs exist**:
+- Don't delete - add migration note in docs/README.md
+- Reference existing content where relevant
+- Note in system-state.md that migration in progress
+
+### 5. Validate
+
+```bash
+# Check structure
+ls -la docs/{00-context,01-product,02-features,03-logs,04-process}
+
+# Count minimum files
+find docs/00-context -name "*.md" | wc -l  # >= 3
+find docs/03-logs -name "*.md" | wc -l     # >= 5
+find docs/04-process -name "*.md" | wc -l  # >= 3
+test -f docs/01-product/prd.md && echo "✓ PRD exists"
+test -f docs/README.md && echo "✓ README exists"
+```
+
+## Rules
+
+**DO**:
+- Complete one section fully before next
+- Use TodoWrite to track progress
+- Populate files (don't leave empty templates)
+- Use discovered content from project
+- Create feature-<name>/ for each major feature found
+- Initialize all 5 log files with format
+- Mark todos completed immediately after finishing
+
+**DON'T**:
+- Skip sections
+- Create empty placeholders
+- Duplicate content across files
+- Delete existing docs
+- Forget to validate at end
+
+## Success Criteria
+
+✅ All 5 tier directories created
+✅ Minimum files in each (00-context: 3, 01-product: 1, 03-logs: 5, 04-process: 3)
+✅ Files populated with project-specific content
+✅ Feature folders created for discovered features
+✅ docs/README.md complete with navigation
+✅ Integration with CLAUDE.md/KNOWLEDGE_BASE.md done
+✅ Validation checks pass
+✅ All todos marked completed
+
+Complete when /docs structure is fully populated and navigable.

package/packages/opencode/command/explain.md

@@ -0,0 +1,18 @@
+---
+name: explain
+description: Explain [code]
+usage: /explain <code-section>
+argument-hint: [file, function, or concept]
+model: claude-3-5-haiku-20241022
+---
+Explain $ARGUMENTS.
+
+## Cover
+- What it does (purpose)
+- How it works (step by step)
+- Why it's designed this way
+- Dependencies and side effects
+- Potential gotchas
+
+Assume reader knows the language but not this codebase.
+

package/packages/opencode/command/git-commit.md

@@ -0,0 +1,14 @@
+---
+name: git-commit
+description: Analyze changes and commit
+usage: /git-commit
+allowed-tools: Bash(git *)
+---
+1. Run `git diff --staged` to see changes
+2. Analyze what was changed and why
+3. Create a commit message:
+   - Format: type(scope): description
+   - Types: feat, fix, refactor, docs, test, chore
+   - Under 72 chars
+   - Body explains WHY if non-obvious
+4. Execute the commit