@rfxlamia/skillkit 1.1.0 → 1.2.0

package/skills/skills/prompt-engineering/references/zero-shot.md

@@ -0,0 +1,74 @@
+# Zero-Shot Prompting
+
+## When to Use
+- Task is well-defined and common in LLM training data
+- No examples available
+- Simple, direct instructions sufficient
+- Token budget is limited
+
+## Best Practices
+✓ Clear, specific instructions
+✓ Define expected output format explicitly
+✓ Include all constraints and requirements
+✓ Specify edge case handling
+
+✗ Avoid ambiguous language
+✗ Don't assume implicit knowledge
+✗ Don't leave format unspecified
+
+## Template (Natural Language)
+```
+Task: [Clear description of what needs to be done]
+
+Requirements:
+- [Requirement 1]
+- [Requirement 2]
+- [Requirement 3]
+
+Output format: [Specify exact format]
+
+Constraints:
+- [Constraint 1]
+- [Constraint 2]
+
+Please [specific action verb] based on the above requirements.
+```
+
+## Template (XML - Claude)
+```xml
+<task>
+  <description>
+    [Clear task description]
+  </description>
+  
+  <requirements>
+    <requirement priority="high">[Requirement 1]</requirement>
+    <requirement priority="medium">[Requirement 2]</requirement>
+  </requirements>
+  
+  <constraints>
+    <constraint>[Constraint 1]</constraint>
+  </constraints>
+  
+  <output_format>
+    [Desired output structure]
+  </output_format>
+</task>
+```
+
+## Examples
+
+### ❌ Bad Zero-Shot
+```
+Translate this to French.
+```
+Problems: No context, no format specified, ambiguous
+
+### ✅ Good Zero-Shot
+```
+Translate the following English text to French.
+Maintain formal tone, preserve technical terms.
+Output only the translation without explanations.
+
+Text: [input text]
+```

package/skills/skills/quick-spec/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: quick-spec
+description: Create implementation-ready technical specifications through conversational discovery, code investigation, and structured documentation. USE WHEN user needs to plan a feature, create tech-spec, or prepare implementation-ready documentation. Triggers on "buat spec", "create tech spec", "plan feature", "specification", or when user describes a feature to build without clear implementation plan.
+category: planning
+---
+
+# Quick Spec
+
+## Overview
+
+Create implementation-ready technical specifications through a 4-step conversational workflow. This skill guides you from vague requirements to a complete tech-spec with tasks, acceptance criteria, and technical context that any developer can use to implement the feature.
+
+**The output meets the "Ready for Development" standard:**
+- **Actionable**: Every task has a clear file path and specific action
+- **Logical**: Tasks are ordered by dependency (lowest level first)
+- **Testable**: All ACs follow Given/When/Then and cover happy path and edge cases
+- **Complete**: All investigation results are inlined; no placeholders or "TBD"
+- **Self-Contained**: A fresh agent can implement the feature without reading the workflow history
+
+---
+
+## Workflow Decision Tree
+
+```
+User wants to build a feature
+        |
+        v
++----------------------------------+
+| Have tech-spec?                  |
++----------------------------------+
+    |              |
+   YES             NO
+    |              |
+    v              v
++---------+  +---------------------+
+| Use     |  | Start quick-spec    |
+| spec    |  | workflow            |
++---------+  +---------------------+
+```
+
+---
+
+## Core Principles
+
+### Step-File Architecture
+
+This workflow uses **micro-file design** for disciplined execution:
+
+- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until directed
+- **Sequential Enforcement**: Sequence within step files must be completed in order, no skipping or optimization
+- **State Tracking**: Progress is documented in output file frontmatter using `stepsCompleted` array
+- **Append-Only Building**: Build the tech-spec by updating content as directed
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: Only proceed to next step when user selects [c] (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, load and read entire next step file, then execute
+
+### Critical Rules (NO EXCEPTIONS)
+
+- **NEVER** load multiple step files simultaneously
+- **ALWAYS** read entire step file before execution
+- **NEVER** skip steps or optimize the sequence
+- **ALWAYS** update frontmatter of output file when completing a step
+- **ALWAYS** follow the exact instructions in the step file
+- **ALWAYS** halt at menus and wait for user input
+- **NEVER** create mental todo lists from future steps
+
+---
+
+## The 4-Step Workflow
+
+### Step 1: Analyze Requirement Delta
+
+**Goal**: Define the technical requirement delta and scope through informed questioning.
+
+**Process**:
+1. **Check for Work in Progress** - Look for existing tech-spec-wip.md
+2. **Greet and Ask for Initial Request** - Get user's feature description
+3. **Quick Orient Scan** - Rapid codebase scan to understand landscape
+4. **Ask Informed Questions** - Ask specific questions based on code findings
+5. **Capture Core Understanding** - Extract title, problem, solution, scope
+6. **Initialize WIP File** - Create tech-spec-wip.md with template
+7. **Present Checkpoint Menu** - [a] Advanced Elicitation, [c] Continue, [p] Party Mode
+
+**Output**: WIP file with Overview section filled
+
+---
+
+### Step 2: Map Technical Constraints
+
+**Goal**: Map the problem statement to specific anchor points in the codebase.
+
+**Process**:
+1. **Load Current State** - Read WIP file from Step 1
+2. **Execute Investigation Path**:
+   - Build on Step 1's quick scan
+   - Read and analyze relevant code files
+   - Document technical context (stack, patterns, files)
+   - Look for project-context.md
+3. **Update WIP File** - Add technical context to frontmatter and Context for Development section
+4. **Present Checkpoint Menu** - [a] Advanced Elicitation, [c] Continue, [p] Party Mode
+
+**Output**: WIP file with technical context documented
+
+---
+
+### Step 3: Generate Implementation Plan
+
+**Goal**: Create the implementation sequence that addresses the requirement delta.
+
+**Process**:
+1. **Load Current State** - Read WIP file with Overview and Context
+2. **Generate Implementation Plan**:
+   - Task breakdown (discrete, ordered, specific files)
+   - Task format: `- [ ] Task N: Description` with File, Action, Notes
+3. **Generate Acceptance Criteria**:
+   - Given/When/Then format
+   - Cover happy path, error handling, edge cases
+4. **Complete Additional Context**:
+   - Dependencies
+   - Testing strategy
+   - Notes (risks, limitations, future considerations)
+5. **Write Complete Spec** - Update WIP file, set status to 'review'
+6. **Auto-continue to Step 4**
+
+**Output**: Complete tech-spec ready for review
+
+---
+
+### Step 4: Review and Finalize
+
+**Goal**: Review the complete spec and finalize it for development.
+
+**Process**:
+1. **Load and Present Complete Spec** - Show the full tech-spec to user
+2. **Handle Review Feedback**:
+   - Make requested changes
+   - Ensure "Ready for Development" standard is met
+   - Answer questions
+3. **Finalize the Spec**:
+   - Update status to 'ready-for-dev'
+   - Rename WIP file to tech-spec-SLUG.md
+4. **Present Final Menu**:
+   - [a] Advanced Elicitation
+   - [r] Adversarial Review (recommended)
+   - [b] Begin Development
+   - [d] Done - exit workflow
+   - [p] Party Mode
+
+**Output**: Finalized tech-spec file ready for implementation
+
+---
+
+## Tech-Spec Template Structure
+
+The output tech-spec follows this structure:
+
+```markdown
+---
+title: 'Feature Name'
+slug: 'feature-name'
+created: '2026-01-15'
+status: 'ready-for-dev'
+stepsCompleted: [1, 2, 3, 4]
+tech_stack: []
+files_to_modify: []
+code_patterns: []
+test_patterns: []
+---
+
+# Tech-Spec: Feature Name
+
+## Overview
+### Problem Statement
+### Solution
+### Scope (In/Out)
+
+## Context for Development
+### Codebase Patterns
+### Files to Reference
+### Technical Decisions
+
+## Implementation Plan
+### Tasks
+### Acceptance Criteria
+
+## Additional Context
+### Dependencies
+### Testing Strategy
+### Notes
+```
+
+---
+
+## Checkpoint Menus
+
+### Step 1-2 Menu
+```
+[a] Advanced Elicitation - dig deeper into requirements
+[c] Continue - proceed to next step
+[p] Party Mode - bring in other experts
+```
+
+### Step 4 Final Menu
+```
+[a] Advanced Elicitation - refine further
+[r] Adversarial Review - critique of the spec (highly recommended)
+[b] Begin Development - start implementing now (not recommended)
+[d] Done - exit workflow
+[p] Party Mode - get expert feedback before dev
+```
+
+---
+
+## Usage Examples
+
+### Example 1: New Feature
+**User**: "I want to add user authentication to my app"
+
+**Agent**: Uses quick-spec workflow to:
+1. Ask about auth methods, user flows, existing user model
+2. Investigate current codebase for auth patterns
+3. Generate tasks: create AuthService, add middleware, update routes, etc.
+4. Create acceptance criteria for login/logout/error cases
+
+### Example 2: API Endpoint
+**User**: "Need an endpoint to export user data as CSV"
+
+**Agent**: Uses quick-spec workflow to:
+1. Ask about data fields, filtering, permissions
+2. Investigate existing API patterns, CSV libraries in use
+3. Generate tasks: create endpoint, add service method, write tests
+4. Create acceptance criteria for export functionality
+
+---
+
+## Integration with Other Workflows
+
+The quick-spec workflow can invoke:
+
+- **Advanced Elicitation** - For deeper requirement discovery
+- **Party Mode** - For bringing in expert perspectives
+- **Quick Dev** - For implementation after spec is finalized
+- **Adversarial Review** - For critical review of the spec
+
+---
+
+## Best Practices
+
+1. **Don't rush Step 1** - Good questions lead to better specs
+2. **Investigate thoroughly in Step 2** - Understanding existing code prevents rework
+3. **Be specific in Step 3** - Vague tasks create implementation confusion
+4. **Get adversarial review** - Step 4's [r] option catches blind spots
+5. **Use fresh context for dev** - After finalizing, start implementation in new context
+
+---
+
+## Output Location
+
+Tech-specs are saved to: IMPLEMENTATION_ARTIFACTS/tech-spec-SLUG.md
+
+Default: project-root/.ai/tech-spec-SLUG.md
+
+---
+
+## Resources
+
+### references/
+- `references/step-01-understand.md` - Step 1 instruction file
+- `references/step-02-investigate.md` - Step 2 instruction file
+- `references/step-03-generate.md` - Step 3 instruction file
+- `references/step-04-review.md` - Step 4 instruction file
+
+### assets/
+- `assets/tech-spec-template.md` - Template for output tech-spec files

package/skills/skills/quick-spec/assets/tech-spec-template.md

@@ -0,0 +1,74 @@
+---
+title: '{title}'
+slug: '{slug}'
+created: '{date}'
+status: 'in-progress'
+stepsCompleted: []
+tech_stack: []
+files_to_modify: []
+code_patterns: []
+test_patterns: []
+---
+
+# Tech-Spec: {title}
+
+**Created:** {date}
+
+## Overview
+
+### Problem Statement
+
+{problem_statement}
+
+### Solution
+
+{solution}
+
+### Scope
+
+**In Scope:**
+{in_scope}
+
+**Out of Scope:**
+{out_of_scope}
+
+## Context for Development
+
+### Codebase Patterns
+
+{codebase_patterns}
+
+### Files to Reference
+
+| File | Purpose |
+| ---- | ------- |
+
+{files_table}
+
+### Technical Decisions
+
+{technical_decisions}
+
+## Implementation Plan
+
+### Tasks
+
+{tasks}
+
+### Acceptance Criteria
+
+{acceptance_criteria}
+
+## Additional Context
+
+### Dependencies
+
+{dependencies}
+
+### Testing Strategy
+
+{testing_strategy}
+
+### Notes
+
+{notes}

package/skills/skills/quick-spec/references/step-01-understand.md

@@ -0,0 +1,189 @@
+---
+name: 'step-01-understand'
+description: 'Analyze the requirement delta between current state and what user wants to build'
+
+workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/create-tech-spec'
+nextStepFile: './step-02-investigate.md'
+skipToStepFile: './step-03-generate.md'
+templateFile: '{workflow_path}/tech-spec-template.md'
+wipFile: '{implementation_artifacts}/tech-spec-wip.md'
+---
+
+# Step 1: Analyze Requirement Delta
+
+**Progress: Step 1 of 4** - Next: Deep Investigation
+
+## RULES:
+
+- MUST NOT skip steps.
+- MUST NOT optimize sequence.
+- MUST follow exact instructions.
+- MUST NOT look ahead to future steps.
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## CONTEXT:
+
+- Variables from `workflow.md` are available in memory.
+- Focus: Define the technical requirement delta and scope.
+- Investigation: Perform surface-level code scans ONLY to verify the delta. Reserve deep dives into implementation consequences for Step 2.
+- Objective: Establish a verifiable delta between current state and target state.
+
+## SEQUENCE OF INSTRUCTIONS
+
+### 0. Check for Work in Progress
+
+a) **Before anything else, check if `{wipFile}` exists:**
+
+b) **IF WIP FILE EXISTS:**
+
+1. Read the frontmatter and extract: `title`, `slug`, `stepsCompleted`
+2. Calculate progress: `lastStep = max(stepsCompleted)`
+3. Present to user:
+
+```
+Hey {user_name}! Found a tech-spec in progress:
+
+**{title}** - Step {lastStep} of 4 complete
+
+Is this what you're here to continue?
+
+[y] Yes, pick up where I left off
+[n] No, archive it and start something new
+```
+
+4. **HALT and wait for user selection.**
+
+a) **Menu Handling:**
+
+- **[y] Continue existing:**
+  - Jump directly to the appropriate step based on `stepsCompleted`:
+    - `[1]` → Load `{nextStepFile}` (Step 2)
+    - `[1, 2]` → Load `{skipToStepFile}` (Step 3)
+    - `[1, 2, 3]` → Load `./step-04-review.md` (Step 4)
+- **[n] Archive and start fresh:**
+  - Rename `{wipFile}` to `{implementation_artifacts}/tech-spec-{slug}-archived-{date}.md`
+
+### 1. Greet and Ask for Initial Request
+
+a) **Greet the user briefly:**
+
+"Hey {user_name}! What are we building today?"
+
+b) **Get their initial description.** Don't ask detailed questions yet - just understand enough to know where to look.
+
+### 2. Quick Orient Scan
+
+a) **Before asking detailed questions, do a rapid scan to understand the landscape:**
+
+b) **Check for existing context docs:**
+
+- Check `{output_folder}` and `{planning_artifacts}`for planning documents (PRD, architecture, epics, research)
+- Check for `**/project-context.md` - if it exists, skim for patterns and conventions
+- Check for any existing stories or specs related to user's request
+
+c) **If user mentioned specific code/features, do a quick scan:**
+
+- Search for relevant files/classes/functions they mentioned
+- Skim the structure (don't deep-dive yet - that's Step 2)
+- Note: tech stack, obvious patterns, file locations
+
+d) **Build mental model:**
+
+- What's the likely landscape for this feature?
+- What's the likely scope based on what you found?
+- What questions do you NOW have, informed by the code?
+
+**This scan should take < 30 seconds. Just enough to ask smart questions.**
+
+### 3. Ask Informed Questions
+
+a) **Now ask clarifying questions - but make them INFORMED by what you found:**
+
+Instead of generic questions like "What's the scope?", ask specific ones like:
+- "`AuthService` handles validation in the controller — should the new field follow that pattern or move it to a dedicated validator?"
+- "`NavigationSidebar` component uses local state for the 'collapsed' toggle — should we stick with that or move it to the global store?"
+- "The epics doc mentions X - is this related?"
+
+**Adapt to {user_skill_level}.** Technical users want technical questions. Non-technical users need translation.
+
+b) **If no existing code is found:**
+
+- Ask about intended architecture, patterns, constraints
+- Ask what similar systems they'd like to emulate
+
+### 4. Capture Core Understanding
+
+a) **From the conversation, extract and confirm:**
+
+- **Title**: A clear, concise name for this work
+- **Slug**: URL-safe version of title (lowercase, hyphens, no spaces)
+- **Problem Statement**: What problem are we solving?
+- **Solution**: High-level approach (1-2 sentences)
+- **In Scope**: What's included
+- **Out of Scope**: What's explicitly NOT included
+
+b) **Ask the user to confirm the captured understanding before proceeding.**
+
+### 5. Initialize WIP File
+
+a) **Create the tech-spec WIP file:**
+
+1. Copy template from `{templateFile}`
+2. Write to `{wipFile}`
+3. Update frontmatter with captured values:
+   ```yaml
+   ---
+   title: '{title}'
+   slug: '{slug}'
+   created: '{date}'
+   status: 'in-progress'
+   stepsCompleted: [1]
+   tech_stack: []
+   files_to_modify: []
+   code_patterns: []
+   test_patterns: []
+   ---
+   ```
+4. Fill in Overview section with Problem Statement, Solution, and Scope
+5. Fill in Context for Development section with any technical preferences or constraints gathered during informed discovery.
+6. Write the file
+
+b) **Report to user:**
+
+"Created: `{wipFile}`
+
+**Captured:**
+
+- Title: {title}
+- Problem: {problem_statement_summary}
+- Scope: {scope_summary}"
+
+### 6. Present Checkpoint Menu
+
+a) **Display menu:**
+
+```
+[a] Advanced Elicitation - dig deeper into requirements
+[c] Continue - proceed to next step
+[p] Party Mode - bring in other experts
+```
+
+b) **HALT and wait for user selection.**
+
+#### Menu Handling:
+
+- **[a]**: Load and execute `{advanced_elicitation}`, then return here and redisplay menu
+- **[c]**: Load and execute `{nextStepFile}` (Map Technical Constraints)
+- **[p]**: Load and execute `{party_mode_exec}`, then return here and redisplay menu
+
+---
+
+## REQUIRED OUTPUTS:
+
+- MUST initialize WIP file with captured metadata.
+
+## VERIFICATION CHECKLIST:
+
+- [ ] WIP check performed FIRST before any greeting.
+- [ ] `{wipFile}` created with correct frontmatter, Overview, Context for Development, and `stepsCompleted: [1]`.
+- [ ] User selected [c] to continue.