@amrhas82/agentic-kit 1.5.0 → 1.7.5

package/packages/claude/skills/docs-builder/references/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/claude/skills/root-cause-tracing/SKILL.md

@@ -1,6 +1,9 @@
 ---
+id: root-cause-tracing
 name: root-cause-tracing
 description: Use when errors occur deep in execution and you need to trace back to find the original trigger - systematically traces bugs backward through call stack, adding instrumentation when needed, to identify source of invalid data or incorrect behavior
+usage: /root-cause-tracing <issue-description>
+auto_trigger: false
 ---
 
 # Root Cause Tracing

package/packages/claude/skills/skill-creator/SKILL.md

@@ -1,6 +1,9 @@
 ---
+id: skill-creator
 name: skill-creator
 description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
+usage: /skill-creator <skill-type> <skill-description>
+auto_trigger: false
 license: Complete terms in LICENSE.txt
 ---
 

package/packages/claude/skills/subagent-spawning/SKILL.md

@@ -0,0 +1,82 @@
+---
+id: subagent-spawning
+name: subagent-spawning
+description: Use when spawning fresh subagents for isolated task execution. Provides TDD-aware templates for 3-process-task-list and other agents.
+usage: Used by 3-process-task-list and other agents for clean subagent execution
+auto_trigger: true
+---
+
+## Auto-Trigger
+
+**APPLIES WHEN:**
+- 3-process-task-list spawning implementer for a task
+- Any agent delegating work to fresh subagent
+- Task isolation needed (prevent context pollution)
+
+**APPLIES TO:**
+- Task list processing
+- Parallel task execution
+- Complex multi-step implementations
+
+## Template A: With TDD (when tdd: yes)
+
+```
+You are implementing Task: {task_description}
+
+CONTEXT:
+{relevant_file_contents}
+
+ACCEPTANCE CRITERIA:
+{task_specific_criteria}
+
+TDD REQUIRED:
+Write test FIRST. Watch it FAIL. Then implement. Then watch it PASS.
+{tdd_note}
+
+VERIFY WITH: {verify_command}
+
+WORKFLOW:
+1. Write test for expected behavior
+2. Run test - MUST see it FAIL (red)
+3. Implement minimal code to pass
+4. Run test - verify it PASSES (green)
+5. Refactor if needed
+6. Report: test output (fail→pass) + changes + concerns
+
+CONSTRAINTS:
+- Do NOT implement before writing test
+- Do NOT skip red-green verification
+- Do NOT reference other tasks
+- Do NOT assume context not provided
+```
+
+## Template B: Without TDD (when tdd: no)
+
+```
+You are implementing Task: {task_description}
+
+CONTEXT:
+{relevant_file_contents}
+
+ACCEPTANCE CRITERIA:
+{task_specific_criteria}
+
+VERIFY WITH: {verify_command}
+
+WORKFLOW:
+1. Implement the task completely
+2. Run verify command BEFORE claiming done
+3. Report: changes + verify output + concerns
+
+CONSTRAINTS:
+- Do NOT reference other tasks
+- Do NOT assume context not provided
+- Do NOT claim done without verify output
+```
+
+## Why Fresh Subagents?
+
+- Task 1 confusion doesn't pollute task 5
+- Each task gets clean reasoning slate
+- Prevents "I already tried that" false memories
+- Forces explicit context = fewer assumptions

package/packages/claude/skills/systematic-debugging/SKILL.md

@@ -1,6 +1,9 @@
 ---
+id: systematic-debugging
 name: systematic-debugging
 description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework (root cause investigation, pattern analysis, hypothesis testing, implementation) that ensures understanding before attempting solutions
+usage: /systematic-debugging <bug-or-error-description>
+auto_trigger: false
 ---
 
 # Systematic Debugging
@@ -111,7 +114,7 @@ You MUST complete each phase before proceeding to the next.
 
    **WHEN error is deep in call stack:**
 
-   **REQUIRED SUB-SKILL:** Use superpowers:root-cause-tracing for backward tracing technique
+   **REQUIRED SUB-SKILL:** Use root-cause-tracing for backward tracing technique
 
    **Quick version:**
    - Where does bad value originate?
@@ -282,7 +285,6 @@ If systematic investigation reveals issue is truly environmental, timing-depende
 - **test-driven-development** - REQUIRED for creating failing test case (see Phase 4, Step 1)
 
 **Complementary skills:**
-- **defense-in-depth** - Add validation at multiple layers after finding root cause
 - **condition-based-waiting** - Replace arbitrary timeouts identified in Phase 2
 - **verification-before-completion** - Verify fix worked before claiming success