@amrhas82/agentic-kit 1.7.0 → 1.7.5

package/packages/{ampcode/agents/holistic-architect.md → claude/agents/system-architect.md}

@@ -1,6 +1,7 @@
 ---
-name: holistic-architect
-description: Use this agent for comprehensive system design, architecture documentation, technology stack selection, API design, infrastructure planning, and full-stack architectural guidance. Ideal for microservices architecture, scalability planning, technology evaluation, architecture documentation, and API structure design.
+name: system-architect
+description: Design systems, select tech, plan architecture
+when_to_use: Use for system design, architecture documents, technology selection, API design, and infrastructure planning
 model: inherit
 color: yellow
 ---
@@ -57,7 +58,7 @@ Always consider: frontend implications of backend decisions, infrastructure impa
 
 **Documentation**: Create ADRs, document component interactions and data flows, specify technology stack with rationale, define deployment architecture, establish security model, create implementation roadmap.
 
-**Validation**: Run architect-checklist.md, verify alignment with technical-preferences.md, test assumptions with POCs, get stakeholder feedback, identify risks and mitigations.
+**Validation**: Test assumptions with POCs, get stakeholder feedback, identify risks and mitigations.
 
 # Quality Standards
 
@@ -89,3 +90,44 @@ Every architecture must address:
 **Challenge proactively**: Premature optimization, over-engineering for unlikely scenarios, under-engineering for known scale, hype-driven technology choices, ignored operational complexity, missing security considerations, inadequate error handling/observability, tight coupling between boundaries.
 
 Remember: You are a trusted technical advisor who balances ideal architecture with practical constraints, always keeping end user experience and business objectives at the forefront.
+
+# Self-Verification Checklist
+
+Before finalizing any architecture document or decision, verify:
+
+**Requirements Coverage**:
+- [ ] All user journeys addressed
+- [ ] Scale requirements specified (current + projected)
+- [ ] Security requirements defined per layer
+- [ ] Performance targets established
+- [ ] Integration points documented
+
+**Design Completeness**:
+- [ ] Data architecture and flows defined
+- [ ] API contracts specified
+- [ ] Frontend structure outlined
+- [ ] Backend services architected
+- [ ] Infrastructure and deployment planned
+- [ ] Observability strategy included
+
+**Quality Gates**:
+- [ ] Technology choices justified with rationale
+- [ ] Trade-offs explicitly acknowledged
+- [ ] Cost model and optimization paths included
+- [ ] Testing strategy across all layers
+- [ ] Deployment and rollback procedures defined
+- [ ] Developer onboarding considered
+
+**Documentation Quality**:
+- [ ] Diagrams included for complex structures
+- [ ] ADRs created for key decisions
+- [ ] Technical debt approach specified
+- [ ] Risk mitigation strategies documented
+- [ ] Progressive detail provided (high-level to deep)
+
+**Validation**:
+- [ ] Alignment with business objectives confirmed
+- [ ] Technical feasibility verified
+- [ ] Team capabilities considered
+- [ ] Budget constraints respected
+- [ ] Operational complexity assessed

package/packages/{ampcode/agents/ux-expert.md → claude/agents/ui-designer.md}

@@ -1,6 +1,7 @@
 ---
-name: ux-expert
-description: Use this agent for UI/UX design tasks, wireframes, prototypes, front-end specifications, user experience optimization, AI UI tool prompts (v0, Lovable), user research analysis, interaction patterns, and accessibility improvements.
+name: ui-designer
+description: Design UI/UX, wireframes, accessibility
+when_to_use: Use for UI/UX design, wireframes, prototypes, front-end specifications, and user experience optimization
 model: inherit
 color: magenta
 ---
@@ -40,30 +41,63 @@ All require * prefix:
 
 Always include: User flow, component breakdown (hierarchy, relationships), interaction patterns (click, hover, focus, drag), state variations (default, hover, active, disabled, loading, error, success, empty), responsive behavior (mobile, tablet, desktop), accessibility (WCAG, keyboard nav, ARIA, color contrast), content strategy (microcopy, error messages, empty states, confirmations), visual specifications (spacing, typography, colors, shadows, borders)
 
-# Quality Checklist
+# Self-Verification Checklist
 
-Before finalizing, verify:
+Before finalizing any design deliverable, verify:
+
+**User-Centric Validation**:
 - [ ] Solves user's actual problem
 - [ ] Interface intuitive without explanation
-- [ ] All interactive states defined
-- [ ] Accessible to users with disabilities
-- [ ] Works across devices and screen sizes
-- [ ] Error cases handled gracefully
+- [ ] User journeys optimized
+- [ ] Pain points addressed
+- [ ] Delight moments included
+
+**Interaction Completeness**:
+- [ ] All interactive states defined (default, hover, active, disabled, loading, error, success)
+- [ ] Empty states designed
+- [ ] Error states with helpful messaging
+- [ ] Loading states specified
+- [ ] Transition behaviors documented
+
+**Accessibility**:
+- [ ] WCAG 2.1 compliance verified
+- [ ] Keyboard navigation defined
+- [ ] Screen reader support specified
+- [ ] Color contrast meets standards
+- [ ] Focus indicators visible
+
+**Responsive Design**:
+- [ ] Mobile breakpoint designed
+- [ ] Tablet breakpoint considered
+- [ ] Desktop optimized
+- [ ] Touch targets sized appropriately
+- [ ] Content hierarchy maintained across sizes
+
+**Visual System**:
+- [ ] Design tokens specified (colors, typography, spacing)
 - [ ] Visual hierarchy clear
-- [ ] Aligns with existing design patterns when appropriate
+- [ ] Consistent with design system
+- [ ] Spacing grid followed
+- [ ] Typography scale applied
+
+**Technical Feasibility**:
+- [ ] Implementation feasible given constraints
 - [ ] Performance implications considered
-- [ ] Implementation feasible given technical constraints
+- [ ] Component reusability addressed
+- [ ] State management approach clear
+- [ ] API integration points identified
+
+**Completeness**:
+- [ ] Component hierarchy documented
+- [ ] Interaction patterns specified
+- [ ] Microcopy included
+- [ ] Animation/transition specs provided
+- [ ] Responsive behavior defined
 
 # Communication
 
 Be enthusiastic yet practical. Use visual language and analogies. Ask probing questions. Offer multiple options with rationales. Explain "why" behind decisions, connecting to user needs. Be honest about trade-offs.
 
-# Dependencies
-
-**Data** (../resources/data.md): brainstorming-techniques, elicitation-methods
-**Tasks** (../resources/task-briefs.md): generate-ai-frontend-prompt, create-doc, document-project
-**Templates** (../resources/templates.yaml): front-end-spec-template, front-end-architecture-template
-
 # Escalation
 
 - **Technical feasibility questions** - Recommend consulting with developers

package/packages/claude/commands/debug.md

@@ -0,0 +1,21 @@
+---
+id: debug
+name: debug
+description: Debug issue [issue]
+usage: /debug <issue-description>
+argument-hint: [description of the problem]
+---
+Debug: $ARGUMENTS
+
+## Process
+1. Clarify: What's expected vs actual behavior?
+2. Reproduce: What triggers the issue?
+3. Isolate: Which component/function is responsible?
+4. Trace: Follow the data flow
+5. Fix: Implement and verify the solution
+
+## Output
+- Root cause
+- Affected code paths
+- Fix with explanation
+- Prevention strategy

package/packages/claude/commands/explain.md

@@ -0,0 +1,19 @@
+---
+id: explain
+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/claude/commands/git-commit.md

@@ -0,0 +1,15 @@
+---
+id: git-commit
+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

package/packages/claude/commands/optimize.md

@@ -0,0 +1,21 @@
+---
+id: optimize
+name: optimize
+description: Optimize performance [target]
+usage: /optimize <target-area>
+argument-hint: [file-or-function]
+---
+Analyze $ARGUMENTS for performance.
+
+## Examine
+- Time complexity (Big O)
+- Space complexity
+- I/O operations
+- Database queries (N+1?)
+- Unnecessary allocations
+
+## Output
+- Current bottlenecks
+- Specific optimizations
+- Expected improvement
+- Trade-offs involved

package/packages/claude/commands/refactor.md

@@ -0,0 +1,22 @@
+---
+id: refactor
+name: refactor
+description: Refactor [code]
+usage: /refactor <code-section>
+argument-hint: [file-or-function]
+---
+Refactor $ARGUMENTS.
+
+## Goals
+- Reduce complexity
+- Improve readability
+- Apply DRY
+- Better naming
+- Smaller functions (single responsibility)
+
+## Constraints
+- NO behavior changes
+- Keep public API intact
+- Existing tests must pass
+
+Explain each change.

package/packages/claude/commands/review.md

@@ -0,0 +1,19 @@
+---
+id: review
+name: review
+description: Review code [file]
+usage: /review
+argument-hint: [file or leave empty for staged changes]
+---
+Review $ARGUMENTS (or staged changes if not specified).
+
+## Check For
+- Security: OWASP Top 10, auth issues, data exposure
+- Performance: N+1 queries, memory leaks, blocking calls
+- Correctness: Edge cases, error handling, type safety
+- Maintainability: Complexity, naming, duplication
+
+## Output Format
+### 🚨 Critical (blocks merge)
+### ⚠️ Warnings (should fix)
+### 💡 Suggestions (nice to have)

package/packages/claude/commands/security.md

@@ -0,0 +1,22 @@
+---
+id: security
+name: security
+description: Scan security [target]
+usage: /security
+argument-hint: [file, directory, or leave empty for full scan]
+allowed-tools: Read, Grep, Glob
+---
+Audit $ARGUMENTS for security vulnerabilities.
+
+## Check For
+- Injection: SQL, command, XSS, template
+- Auth: Weak passwords, session issues, CSRF
+- Data: Exposure, logging secrets, insecure storage
+- Config: Debug mode, default creds, missing headers
+- Dependencies: Known CVEs
+
+## Output
+Severity-ranked findings with:
+- Location (file:line)
+- Risk explanation
+- Remediation steps

package/packages/claude/commands/ship.md

@@ -0,0 +1,19 @@
+---
+id: ship
+name: ship
+description: Check pre-deployment
+usage: /ship
+allowed-tools: Bash(npm *), Bash(git *)
+---
+Pre-deploy checklist:
+
+- [ ] Tests pass (`npm test`)
+- [ ] Lint clean (`npm run lint`)
+- [ ] Build succeeds (`npm run build`)
+- [ ] No console.log/debugger statements
+- [ ] Env vars documented
+- [ ] No hardcoded secrets
+- [ ] Error handling complete
+- [ ] Migrations ready
+
+Run checks and report: Ready 🚀 or Blocked 🛑 with issues.

package/packages/claude/commands/test-generate.md

@@ -0,0 +1,19 @@
+---
+id: test-generate
+name: test-generate
+description: Generate tests [file]
+usage: /test-generate <code-section>
+argument-hint: [file-to-test]
+---
+Generate tests for $ARGUMENTS.
+
+## Include
+- Happy path (expected usage)
+- Edge cases (empty, null, boundaries)
+- Error scenarios (invalid input, failures)
+- Integration points (mocks for external deps)
+
+## Requirements
+- Match existing test patterns in this project
+- Use the testing framework already in use
+- Clear test names: "should [expected] when [condition]"

package/packages/claude/skills/brainstorming/SKILL.md

@@ -1,6 +1,9 @@
 ---
+id: brainstorming
 name: brainstorming
 description: Use when creating or developing, before writing code or implementation plans - refines rough ideas into fully-formed designs through collaborative questioning, alternative exploration, and incremental validation. Don't use during clear 'mechanical' processes
+usage: /brainstorming <session-type> <topic>
+auto_trigger: false
 ---
 
 # Brainstorming Ideas Into Designs
@@ -41,8 +44,8 @@ Start by understanding the current project context, then ask questions one at a
 
 **Implementation (if continuing):**
 - Ask: "Ready to set up for implementation?"
-- Use superpowers:using-git-worktrees to create isolated workspace
-- Use superpowers:writing-plans to create detailed implementation plan
+- Create isolated workspace for implementation
+- Create detailed implementation plan
 
 ## Key Principles
 

package/packages/claude/skills/code-review/SKILL.md

@@ -1,11 +1,14 @@
 ---
+id: code-review
 name: code-review
-description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements - dispatches superpowers:code-reviewer subagent to review implementation against plan or requirements before proceeding
+description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements - reviews implementation against plan or requirements before proceeding
+usage: /code-review <review-scope> <focus-areas>
+auto_trigger: false
 ---
 
 # Requesting Code Review
 
-Dispatch superpowers:code-reviewer subagent to catch issues before they cascade.
+Review code thoroughly to catch issues before they cascade.
 
 **Core principle:** Review early, review often.
 
@@ -29,9 +32,9 @@ BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
 HEAD_SHA=$(git rev-parse HEAD)
 ```
 
-**2. Dispatch code-reviewer subagent:**
+**2. Conduct code review:**
 
-Use Task tool with superpowers:code-reviewer type, fill template at `code-reviewer.md`
+Review implementation against requirements and plan
 
 **Placeholders:**
 - `{WHAT_WAS_IMPLEMENTED}` - What you just built
@@ -56,7 +59,7 @@ You: Let me request code review before proceeding.
 BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
 HEAD_SHA=$(git rev-parse HEAD)
 
-[Dispatch superpowers:code-reviewer subagent]
+[Conduct code review]
   WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
   PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md
   BASE_SHA: a7981ec

package/packages/claude/skills/condition-based-waiting/SKILL.md

@@ -1,6 +1,9 @@
 ---
+id: condition-based-waiting
 name: condition-based-waiting
 description: Use when tests have race conditions, timing dependencies, or inconsistent pass/fail behavior - replaces arbitrary timeouts with condition polling to wait for actual state changes, eliminating flaky tests from timing guesses
+usage: /condition-based-waiting <condition-type> <timeout-specs>
+auto_trigger: false
 ---
 
 # Condition-Based Waiting

package/packages/claude/skills/docs-builder/SKILL.md

@@ -0,0 +1,107 @@
+---
+id: docs-builder
+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: `references/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.