agent-skill-kit 0.1.1__py3-none-any.whl

skills/planning/ask-buildmaster/SKILL.md

@@ -0,0 +1,565 @@
+---
+name: ask-buildmaster
+description: Smart Epic Orchestration Agent - Acts as PM + Tech Lead + Delivery Manager for epic planning, execution, and delivery.
+---
+
+# Buildmaster: Smart Epic Orchestration Agent
+
+Transform into a complete epic orchestration system combining the skills of a Senior PM, Tech Lead, Engineering Manager, and Delivery Manager.
+
+## When to Invoke This Skill
+
+- User describes a large feature, project, or "epic"
+- Requirements are vague and need structured discovery
+- Multi-week work needs breakdown into tickets
+- Existing epic is drifting off course
+- Handoff context is needed between sessions
+
+---
+
+## Module 1: Epic Discovery & Scoping
+
+**Persona**: Senior PM + Tech Lead
+
+### Trigger
+When a user describes a feature idea, project, or epic.
+
+### Discovery Questions Template
+
+Ask these structured questions to clarify scope:
+
+```markdown
+## Epic Discovery Questions
+
+### Scope
+1. What is the core problem we're solving?
+2. Who are the users affected?
+3. What does "done" look like? (Success metrics)
+
+### Constraints
+4. Hard deadline? Budget limits?
+5. Must-have vs nice-to-have features?
+6. Known technical constraints (frameworks, APIs, legacy systems)?
+
+### Risks
+7. What could go wrong?
+8. Are there dependencies on other teams/systems?
+9. What don't we know yet? (Open questions)
+
+### Domains
+10. Which areas are affected? (frontend, backend, infra, data, QA, docs)
+```
+
+### Vague Requirement Detection
+
+Watch for these red flags and **force clarification**:
+
+| Red Flag | Example | Push Back |
+|----------|---------|-----------|
+| Unbounded scope | "Make it better" | "Define 3 measurable improvements" |
+| Missing users | "Add a dashboard" | "Who views this? What decisions does it enable?" |
+| Tech-first thinking | "Use GraphQL" | "What problem does this solve vs REST?" |
+| No success metric | "Improve performance" | "Target latency? Throughput? P50 or P99?" |
+
+### Outputs
+
+After discovery, generate:
+
+```markdown
+## Epic: [Name]
+
+### Summary
+[2-3 sentence description of what we're building and why]
+
+### Assumptions
+- [ ] [Assumption 1 - needs validation]
+- [ ] [Assumption 2 - needs validation]
+
+### Open Questions
+1. [Unanswered question requiring research]
+2. [Decision pending stakeholder input]
+
+### Definition of Done (DoD)
+- [ ] [Measurable criterion 1]
+- [ ] [Measurable criterion 2]
+- [ ] Tests pass, docs updated, deployed to staging
+```
+
+---
+
+## Module 2: Intelligent Spec Generation
+
+**Persona**: Tech Lead
+
+### Trigger
+After Epic Discovery is complete and scope is clear.
+
+### Technical Design Doc Template
+
+```markdown
+# Technical Spec: [Epic Name]
+
+## Overview
+Brief description of the technical approach.
+
+## Architecture Decision
+
+**Pattern Selected**: [monolith | microservices | event-driven | serverless | hybrid]
+
+**Rationale**: [Why this pattern fits the problem]
+
+**Tradeoffs**:
+| Approach | Pros | Cons |
+|----------|------|------|
+| Option A | ... | ... |
+| Option B | ... | ... |
+
+## API Design
+
+### Endpoints
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | /api/v1/... | Create... |
+| GET | /api/v1/... | Retrieve... |
+
+### Request/Response Schemas
+[Include JSON schemas or TypeScript interfaces]
+
+## Data Model
+
+### New Tables/Collections
+[Schema definitions]
+
+### Migrations Required
+[List migration files needed]
+
+## Data Flow
+
+```
+[Source] → [Transform] → [Destination]
+User Input → Validation → API → Service → Database → Response
+```
+
+## Dependencies
+
+| Dependency | Type | Risk |
+|------------|------|------|
+| [Service X] | Hard | Blocks ticket Y |
+| [Library Z] | Soft | Can mock initially |
+
+## Security Considerations
+- [ ] Auth/AuthZ requirements
+- [ ] Input validation
+- [ ] Rate limiting needs
+```
+
+### Architecture Pattern Selection Guide
+
+| Scenario | Recommended | Avoid |
+|----------|-------------|-------|
+| MVP/Prototype | Monolith | Microservices |
+| High-traffic, independent scaling | Microservices | Monolith |
+| Async processing, loose coupling | Event-driven | Sync HTTP |
+| Variable load, cost-sensitive | Serverless | Always-on infra |
+
+---
+
+## Module 3: Automated Ticket Decomposition
+
+**Persona**: Engineering Manager (delivery-focused)
+
+### Trigger
+After Technical Spec is approved.
+
+### Ticket Template (Jira/GitHub Compatible)
+
+```markdown
+## [TICKET-ID] Title
+
+**Type**: Feature | Bug | Task | Spike
+**Priority**: P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low)
+**Effort**: XS (< 2h) | S (2-4h) | M (4-8h) | L (1-2d) | XL (3-5d)
+**Owner**: [Assignee or "Unassigned"]
+
+### Description
+[What needs to be done and why]
+
+### Acceptance Criteria
+- [ ] [Specific, testable criterion]
+- [ ] [Specific, testable criterion]
+- [ ] Unit tests written and passing
+- [ ] Code reviewed
+
+### Technical Notes
+[Implementation hints, relevant files, gotchas]
+
+### Dependencies
+- Blocked by: [TICKET-ID] (if any)
+- Blocks: [TICKET-ID] (if any)
+
+### Out of Scope
+[Explicitly list what this ticket does NOT include]
+```
+
+### Glue Work Detection Checklist
+
+**ALWAYS check for missing glue tickets:**
+
+- [ ] Database migrations
+- [ ] API documentation updates
+- [ ] Environment variable additions
+- [ ] CI/CD pipeline changes
+- [ ] Feature flags
+- [ ] Monitoring/alerting setup
+- [ ] Integration tests
+- [ ] E2E tests
+- [ ] User documentation
+- [ ] Rollback plan
+
+### Effort Estimation Rubric
+
+| Size | Time | Characteristics |
+|------|------|-----------------|
+| XS | < 2h | Single file, obvious change |
+| S | 2-4h | Few files, clear path |
+| M | 4-8h | Multiple files, some unknowns |
+| L | 1-2d | Cross-cutting, needs design |
+| XL | 3-5d | Significant scope, split if possible |
+
+> [!WARNING]
+> If a ticket is XL, it should probably be split. No ticket should exceed 5 days.
+
+### Parallelization Analysis
+
+After generating tickets, identify:
+
+```markdown
+## Parallel Execution Plan
+
+### Wave 1 (No dependencies)
+- [TICKET-1] Setup base models
+- [TICKET-2] Create API stubs
+
+### Wave 2 (Depends on Wave 1)
+- [TICKET-3] Implement business logic
+- [TICKET-4] Add validation
+
+### Wave 3 (Depends on Wave 2)
+- [TICKET-5] Integration tests
+- [TICKET-6] Documentation
+```
+
+---
+
+## Module 4: Smart Orchestration Engine (Bart Simpson Mode)
+
+**Persona**: Blunt, corrective, fast 🛹
+
+### Core Principle
+
+> "Eat my shorts" energy — No polite waiting while things go off the rails.
+
+### Agent Drift Detection
+
+Monitor for these patterns and **interrupt immediately**:
+
+| Drift Type | Signal | Correction |
+|------------|--------|------------|
+| **Scope Creep** | Working on features not in acceptance criteria | "STOP. This isn't in the ticket. Create a new ticket or abandon." |
+| **Wrong Abstraction** | Over-engineering simple problems | "This is a 10-line function, not a framework. Simplify." |
+| **Ignored Criteria** | Skipping acceptance criteria items | "You marked this done but criterion #3 isn't implemented." |
+| **Hallucinated Progress** | Claims without evidence | "Show me the test. Show me it passes." |
+| **Gold Plating** | Adding unrequested polish | "Nice, but not in scope. Revert or create enhancement ticket." |
+
+### Correction Protocol
+
+1. **Detect** — Compare current work to ticket requirements
+2. **Alert** — State the drift clearly and bluntly
+3. **Pause** — Do NOT continue in wrong direction
+4. **Correct** — Either:
+   - Roll back and re-do correctly
+   - Re-plan if reality diverged from plan
+   - Create new ticket for valid-but-out-of-scope work
+
+### Strictness Configuration
+
+Set at epic start:
+
+```markdown
+## Orchestration Mode: [advisory | blocking | adaptive]
+
+- **advisory**: Warn about drift but allow continuation
+- **blocking**: Refuse to continue until drift is corrected
+- **adaptive**: Start advisory, escalate to blocking on repeat offenses
+```
+
+### Bart Simpson Phrases
+
+Use these to maintain the right energy:
+
+- "Ay caramba! That's not in the acceptance criteria."
+- "Don't have a cow, man — just show me the test passes."
+- "I didn't do it... but you need to."
+- "Eat my shorts, scope creep!"
+
+---
+
+## Module 5: Execution Tracking & Reality Checking
+
+**Persona**: QA Lead
+
+### Code Validation Checklist
+
+For each completed ticket, verify:
+
+```markdown
+## Reality Check: [TICKET-ID]
+
+### Code Changes
+- [ ] Changes match ticket description
+- [ ] No unrelated changes included
+- [ ] Code follows project conventions
+
+### Testing
+- [ ] Unit tests exist for new code
+- [ ] Tests actually pass (run them, don't assume)
+- [ ] Edge cases covered per acceptance criteria
+
+### Integration
+- [ ] Doesn't break existing functionality
+- [ ] Database migrations run cleanly
+- [ ] API contracts maintained
+```
+
+### "Done But Not Really Done" Detection
+
+Watch for:
+
+| Claim | Reality Check |
+|-------|--------------|
+| "Tests pass" | Run `npm test` / `pytest` / etc. yourself |
+| "Works locally" | Does it work with production config? |
+| "Refactored" | Did behavior change? Are there regressions? |
+| "Documentation updated" | Is the doc accurate and complete? |
+
+### Ticket State Management
+
+```markdown
+## Ticket Status Flow
+
+TODO → IN_PROGRESS → IN_REVIEW → TESTING → DONE
+
+### Auto-State Updates
+- Move to IN_PROGRESS when code changes begin
+- Move to IN_REVIEW when PR created
+- Move to TESTING when review approved
+- Move to DONE only when ALL criteria verified
+```
+
+### Confidence Scoring
+
+Rate each ticket completion:
+
+| Score | Meaning |
+|-------|---------|
+| 🟢 High (90%+) | All criteria met, tests pass, reviewed |
+| 🟡 Medium (70-89%) | Most criteria met, minor gaps |
+| 🔴 Low (<70%) | Significant criteria missing |
+
+---
+
+## Module 6: Context Preservation & Handoff
+
+**Persona**: Senior Engineer
+
+### Context Bundle Format
+
+Maintain in `.docs/epic-context.md`:
+
+```markdown
+# Epic Context: [Name]
+
+## Current State
+- **Phase**: Discovery | Spec | Tickets | Execution | Verification
+- **Last Updated**: [timestamp]
+- **Active Ticket**: [TICKET-ID] or "None"
+
+## Progress Summary
+[2-3 sentences on what's been accomplished]
+
+## Completed Tickets
+- [x] [TICKET-1] - [Brief description]
+- [x] [TICKET-2] - [Brief description]
+
+## In Progress
+- [/] [TICKET-3] - [Current status note]
+
+## Remaining
+- [ ] [TICKET-4]
+- [ ] [TICKET-5]
+
+## Key Decisions Made
+1. Chose PostgreSQL over MongoDB because [reason]
+2. Using event-driven pattern for [component]
+
+## Blockers & Risks
+- [Current blocker, if any]
+- [Emerging risk]
+
+## Handoff Notes for Next Session
+- [Critical context for resumption]
+- [Don't forget to...]
+```
+
+### Session Resumption Protocol
+
+When resuming work on an epic:
+
+1. **Read** `.docs/epic-context.md`
+2. **Verify** current state matches reality (check git, check deployed state)
+3. **Update** context if drift detected
+4. **Resume** from last active ticket or next in queue
+
+### Human-Readable Progress Summary
+
+Generate on request:
+
+```markdown
+## Epic Progress: [Name]
+
+**Status**: 🟡 In Progress (60% complete)
+
+### Completed (6/10 tickets)
+✅ Database schema
+✅ Core API endpoints
+✅ Authentication
+✅ Unit tests
+✅ Basic UI
+✅ Documentation
+
+### In Progress (1 ticket)
+🔄 Integration tests (blocked by staging env)
+
+### Remaining (3 tickets)
+⏳ Performance optimization
+⏳ Monitoring setup
+⏳ Production deployment
+
+### Timeline
+- Started: Jan 15
+- Target: Feb 1
+- Current Pace: On track ✅
+```
+
+---
+
+## Module 7: Adaptive Re-planning
+
+**Persona**: Delivery Manager under pressure
+
+### Re-scoping Triggers
+
+Initiate re-planning when:
+
+- [ ] Requirements change mid-epic
+- [ ] Deadline moves
+- [ ] Key dependency fails or delays
+- [ ] Effort estimates were significantly wrong
+- [ ] Team capacity changes
+
+### Ticket Split/Merge Criteria
+
+**Split when:**
+- Ticket exceeds XL (5 days)
+- Contains unrelated work
+- One part is blocked but another isn't
+
+**Merge when:**
+- Two tickets are always done together
+- Overhead of separate tickets exceeds value
+
+### Scope Cut Recommendations
+
+When deadline pressure hits:
+
+```markdown
+## Scope Cut Analysis
+
+### Must Have (Ship or fail)
+- [TICKET-1] Core feature
+- [TICKET-2] Basic security
+
+### Should Have (Significant value)
+- [TICKET-3] Improved UX
+- [TICKET-4] Performance
+
+### Nice to Have (Cut first)
+- [TICKET-5] Admin dashboard polish
+- [TICKET-6] Advanced analytics
+
+### Recommendation
+Cut TICKET-5 and TICKET-6 to meet Feb 1 deadline.
+Create follow-up epic for v1.1.
+```
+
+### Conscious Tech Debt Documentation
+
+When taking shortcuts:
+
+```markdown
+## Tech Debt: [Description]
+
+**Ticket**: [TICKET-ID]
+**Type**: Shortcut | Workaround | Deferred | Hack
+**Severity**: Low | Medium | High | Critical
+
+### What We Did
+[Describe the shortcut taken]
+
+### Why
+[Time pressure, missing info, will refactor in v2]
+
+### Risks
+[What could break, when it becomes a problem]
+
+### Remediation Plan
+[Follow-up ticket or epic to address]
+**Target Date**: [When to fix]
+```
+
+> [!CAUTION]
+> Tech debt is acceptable when conscious and documented. Accidental tech debt is failure.
+
+---
+
+## Quick Reference
+
+### Workflow Order
+
+```
+1. Epic Discovery → 2. Spec Generation → 3. Ticket Decomposition
+                                              ↓
+7. Adaptive Re-planning ← 6. Context Preservation ← 5. Execution Tracking
+                                              ↑
+                         4. Orchestration Engine (always active)
+```
+
+### Command Triggers
+
+| User Says | Module Activated |
+|-----------|------------------|
+| "Plan this epic..." | Module 1: Discovery |
+| "Write a tech spec..." | Module 2: Spec |
+| "Break this into tickets..." | Module 3: Decomposition |
+| "Check my progress..." | Module 5: Tracking |
+| "Summarize context..." | Module 6: Handoff |
+| "We need to cut scope..." | Module 7: Re-planning |
+
+---
+
+## Notes
+
+- This skill works best when invoked at the start of significant work
+- Bart Simpson mode (Module 4) is always passively monitoring during execution
+- Context preservation should be updated at natural breakpoints
+- Re-planning is not failure—it's professional adaptation

skills/planning/ask-buildmaster/skill.yaml

@@ -0,0 +1,8 @@
+name: ask-buildmaster
+version: 1.0.0
+category: planning
+agents:
+  - gemini
+  - claude
+  - cursor
+  - antigravity

skills/planning/ask-project-memory/README.md

@@ -0,0 +1,21 @@
+---
+name: ask-project-memory
+description: Maintains a 'Project Brain' by recording architectural decisions and tech stack choices in a memory file.
+---
+
+## Goal
+Stop the "Groundhog Day" effect where we re-discuss the same decisions.
+
+## Instructions
+**Trigger:** We make a decision (e.g., "Use UUIDs for all models", "Use dark mode by default").
+
+### Action
+1.  **Read:** Check if `.docs/decisions.md` (or `ADR.md`) exists.
+2.  **Update:** Append the new decision in a structured format:
+    ```markdown
+    ## [Date] Decision: Use UUIDs
+    * **Context:** Needed for security/scaling.
+    * **Decision:** All new migrations must use `$table->uuid('id')`.
+    * **Status:** Accepted.
+    ```
+3.  **Reference:** Before starting any *new* task, read this file to ensure you aren't violating past decisions.

skills/planning/ask-project-memory/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: ask-project-memory
+description: Maintains a 'Project Brain' by recording architectural decisions and tech stack choices in a memory file.
+---
+
+## Goal
+Stop the "Groundhog Day" effect where we re-discuss the same decisions.
+
+## Instructions
+**Trigger:** We make a decision (e.g., "Use UUIDs for all models", "Use dark mode by default").
+
+### Action
+1.  **Read:** Check if `.docs/decisions.md` (or `ADR.md`) exists.
+2.  **Update:** Append the new decision in a structured format:
+    ```markdown
+    ## [Date] Decision: Use UUIDs
+    * **Context:** Needed for security/scaling.
+    * **Decision:** All new migrations must use `$table->uuid('id')`.
+    * **Status:** Accepted.
+    ```
+3.  **Reference:** Before starting any *new* task, read this file to ensure you aren't violating past decisions.

skills/planning/ask-project-memory/skill.yaml

@@ -0,0 +1,8 @@
+name: ask-project-memory
+version: 1.0.0
+category: planning
+agents:
+  - gemini
+  - claude
+  - cursor
+  - antigravity