@atlashub/smartstack-cli 1.13.1 → 1.14.0

package/templates/skills/apex/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: apex
+description: Systematic implementation using APEX methodology (Analyze-Plan-Execute-eXamine) with progressive step loading and context refresh.
+argument-hint: "[-a] [-x] [-s] [-t] [-e] [-i] [-b] [-pr] [-r <task-id>] <task description>"
+---
+
+<objective>
+Execute systematic implementation workflows using the APEX methodology. This skill uses progressive step loading to minimize context usage and maintain fresh context throughout the workflow.
+</objective>
+
+<quick_start>
+**Basic usage:**
+
+```bash
+/apex add authentication middleware
+```
+
+**Recommended workflow (autonomous with save):**
+
+```bash
+/apex -a -s implement user registration
+```
+
+**With adversarial review:**
+
+```bash
+/apex -a -x -s fix login bug
+```
+
+**Flags:**
+
+- `-a` (auto): Skip confirmations
+- `-s` (save): Save outputs to `.claude/output/apex/`
+- `-x` (examine): Include adversarial code review
+- `-t` (test): Create and run tests
+- `-e` (economy): No subagents, direct tool usage
+
+See `<parameters>` for complete flag list.
+</quick_start>
+
+<parameters>
+
+<flags>
+**Enable flags (turn ON):**
+| Short | Long | Description |
+|-------|------|-------------|
+| `-a` | `--auto` | Autonomous mode: skip confirmations, auto-approve plans |
+| `-x` | `--examine` | Auto-examine mode: proceed to adversarial review |
+| `-s` | `--save` | Save mode: output each step to `.claude/output/apex/` |
+| `-t` | `--test` | Test mode: include test creation and runner steps |
+| `-e` | `--economy` | Economy mode: no subagents, save tokens |
+| `-r` | `--resume` | Resume mode: continue from a previous task |
+| `-b` | `--branch` | Branch mode: verify not on main, create branch if needed |
+| `-pr` | `--pull-request` | PR mode: create pull request at end (enables -b) |
+| `-i` | `--interactive` | Interactive mode: configure flags via AskUserQuestion |
+
+**Disable flags (turn OFF):**
+| Short | Long | Description |
+|-------|------|-------------|
+| `-A` | `--no-auto` | Disable auto mode |
+| `-X` | `--no-examine` | Disable examine mode |
+| `-S` | `--no-save` | Disable save mode |
+| `-T` | `--no-test` | Disable test mode |
+| `-E` | `--no-economy` | Disable economy mode |
+| `-B` | `--no-branch` | Disable branch mode |
+| `-PR` | `--no-pull-request` | Disable PR mode |
+</flags>
+
+<examples>
+```bash
+# Basic usage
+/apex add auth middleware
+
+# Autonomous mode (no confirmations)
+/apex -a add auth middleware
+
+# Save outputs for review
+/apex -s add auth middleware
+
+# With adversarial review
+/apex -x add auth middleware
+
+# Full autonomous with examine and save
+/apex -a -x -s add auth middleware
+
+# Include test creation and runner
+/apex -t add auth middleware
+
+# Resume a previous task
+/apex -r 01-auth-middleware
+/apex -r 01 # Partial match supported
+
+# Combined flags
+/apex -a -x -s -t add auth middleware
+
+# Interactive mode (configure flags via menu)
+/apex -i add auth middleware
+
+# Economy mode (save tokens, no subagents)
+/apex -e add auth middleware
+
+# Branch mode (ensure not on main, create branch if needed)
+/apex -b add auth middleware
+
+# Create PR at end (automatically enables -b)
+/apex -pr add auth middleware
+/apex -a -pr add auth middleware # Auto + PR mode
+
+# Full workflow: auto + examine + save + tests + PR
+/apex -a -x -s -t -pr add auth middleware
+```
+</examples>
+
+<parsing_rules>
+**Flag parsing:**
+
+1. Defaults loaded from `steps/step-00-init.md` `<defaults>` section
+2. Command-line flags override defaults
+3. Flags removed from input, remainder becomes `{task_description}`
+4. Task ID generated as `NN-kebab-case-description`
+</parsing_rules>
+
+</parameters>
+
+<output_structure>
+**When `{save_mode}` = true:**
+
+All outputs saved to PROJECT directory:
+```
+.claude/output/apex/{task-id}/
+├── 00-context.md     # Params, user request, timestamp
+├── 01-analyze.md     # Analysis findings
+├── 02-plan.md        # Implementation plan
+├── 03-execute.md     # Execution log
+├── 04-validate.md    # Validation results
+├── 05-examine.md     # Review findings (if -x)
+├── 06-resolve.md     # Resolution log (if -x)
+├── 07-tests.md       # Test creation (if -t)
+├── 08-run-tests.md   # Test runner log (if -t)
+└── 09-finish.md      # PR creation (if -pr)
+```
+</output_structure>
+
+<resume_workflow>
+**Resume mode (`-r {task-id}`):**
+
+When provided, step-00 will:
+
+1. Locate the task folder in `.claude/output/apex/`
+2. Read `00-context.md` to restore state
+3. Find the last completed step
+4. Continue from the next step
+</resume_workflow>
+
+<workflow>
+**Standard flow:**
+1. Parse flags and task description
+2. If `-r`: Execute resume workflow
+3. If `-s`: Create output folder and 00-context.md
+4. Load step-01-analyze.md -> gather context
+5. Load step-02-plan.md -> create strategy
+6. Load step-03-execute.md -> implement
+7. Load step-04-validate.md -> verify
+8. If `--test`: Load step-07-tests.md -> create tests
+9. If `--test`: Load step-08-run-tests.md -> run until green
+10. If `-x` or user requests: Load step-05-examine.md -> adversarial review
+11. If findings: Load step-06-resolve.md -> fix findings
+12. If `-pr`: Load step-09-finish.md -> create pull request
+</workflow>
+
+<state_variables>
+**Persist throughout all steps:**
+
+| Variable                | Type    | Description                                            |
+| ----------------------- | ------- | ------------------------------------------------------ |
+| `{task_description}`    | string  | What to implement (flags removed)                      |
+| `{feature_name}`        | string  | Kebab-case name (e.g., `add-auth-middleware`)          |
+| `{task_id}`             | string  | Full identifier (e.g., `01-add-auth-middleware`)       |
+| `{acceptance_criteria}` | list    | Success criteria (inferred or explicit)                |
+| `{auto_mode}`           | boolean | Skip confirmations                                     |
+| `{examine_mode}`        | boolean | Auto-proceed to adversarial review                     |
+| `{save_mode}`           | boolean | Save outputs to .claude/output/apex/                   |
+| `{test_mode}`           | boolean | Include test steps (07-08)                             |
+| `{economy_mode}`        | boolean | No subagents, direct tool usage only                   |
+| `{branch_mode}`         | boolean | Verify not on main, create branch if needed            |
+| `{pr_mode}`             | boolean | Create pull request at end                             |
+| `{interactive_mode}`    | boolean | Configure flags interactively                          |
+| `{resume_task}`         | string  | Task ID to resume (if -r provided)                     |
+| `{output_dir}`          | string  | Full path to output directory                          |
+| `{branch_name}`         | string  | Created branch name (if branch_mode)                   |
+
+</state_variables>
+
+<entry_point>
+
+**FIRST ACTION:** Load `steps/step-00-init.md`
+
+</entry_point>
+
+<step_files>
+**Progressive loading - only load current step:**
+
+| Step | File                         | Purpose                                              |
+| ---- | ---------------------------- | ---------------------------------------------------- |
+| 00   | `steps/step-00-init.md`      | Parse flags, create output folder, initialize state  |
+| 01   | `steps/step-01-analyze.md`   | Pure context gathering (what exists, not what to do) |
+| 02   | `steps/step-02-plan.md`      | File-by-file implementation strategy                 |
+| 03   | `steps/step-03-execute.md`   | Todo-driven implementation                           |
+| 04   | `steps/step-04-validate.md`  | Self-check and validation                            |
+| 05   | `steps/step-05-examine.md`   | Adversarial code review (optional)                   |
+| 06   | `steps/step-06-resolve.md`   | Finding resolution (optional)                        |
+| 07   | `steps/step-07-tests.md`     | Test analysis and creation (if --test)               |
+| 08   | `steps/step-08-run-tests.md` | Test runner loop until green (if --test)             |
+| 09   | `steps/step-09-finish.md`    | Create pull request (if --pull-request)              |
+
+</step_files>
+
+<execution_rules>
+
+- **Load one step at a time** - Only load the current step file
+- **ULTRA THINK** before major decisions
+- **Persist state variables** across all steps
+- **Follow next_step directive** at end of each step
+- **Save outputs** if `{save_mode}` = true (write to step file)
+- **Use parallel agents** for independent exploration tasks (unless economy_mode)
+</execution_rules>
+
+<success_criteria>
+
+- Each step loaded progressively
+- All validation checks passing
+- Outputs saved if `{save_mode}` enabled
+- Tests passing if `{test_mode}` enabled
+- Clear completion summary provided
+</success_criteria>

package/templates/skills/apex/steps/step-00-init.md

@@ -0,0 +1,203 @@
+---
+name: step-00-init
+description: Initialize APEX workflow - parse flags, detect continuation, setup state
+next_step: steps/step-01-analyze.md
+---
+
+# Step 0: Initialization
+
+## MANDATORY EXECUTION RULES:
+
+- NEVER skip flag parsing
+- ALWAYS parse ALL flags before any other action
+- ONLY check for resume if {resume_task} is set
+- YOU ARE AN INITIALIZER, not an executor
+- FORBIDDEN to load step-01 until init is complete
+
+## YOUR TASK:
+
+Initialize the APEX workflow by parsing flags, detecting continuation state, and setting up the execution environment.
+
+---
+
+<defaults>
+## Default Configuration
+
+```yaml
+auto_mode: false      # -a: Skip confirmations
+examine_mode: false   # -x: Auto-proceed to adversarial review
+save_mode: false      # -s: Save outputs to .claude/output/apex/
+test_mode: false      # -t: Include test creation and runner steps
+economy_mode: false   # -e: No subagents, save tokens
+```
+</defaults>
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Parse Flags and Input
+
+**Step 1: Load defaults from config above**
+
+```
+{auto_mode}    = false
+{examine_mode} = false
+{save_mode}    = false
+{test_mode}    = false
+{economy_mode} = false
+```
+
+**Step 2: Parse user input and override defaults:**
+
+```
+Enable flags (lowercase - turn ON):
+  -a or --auto     -> {auto_mode} = true
+  -x or --examine  -> {examine_mode} = true
+  -s or --save     -> {save_mode} = true
+  -t or --test     -> {test_mode} = true
+  -e or --economy  -> {economy_mode} = true
+
+Disable flags (UPPERCASE - turn OFF):
+  -A or --no-auto         -> {auto_mode} = false
+  -X or --no-examine      -> {examine_mode} = false
+  -S or --no-save         -> {save_mode} = false
+  -T or --no-test         -> {test_mode} = false
+  -E or --no-economy      -> {economy_mode} = false
+
+Other:
+  -r or --resume   -> {resume_task} = <next argument>
+  -i or --interactive -> {interactive_mode} = true
+  Remainder        -> {task_description}
+```
+
+**Step 3: Generate feature_name and task_id:**
+
+```
+{feature_name} = kebab-case-description
+Example: "add user authentication" -> "add-user-authentication"
+
+{task_id} = NN-{feature_name}
+- Auto-detect next available number from .claude/output/apex/
+- Example: "01-add-user-authentication"
+```
+
+### 2. Check Resume Mode
+
+**ONLY execute if {resume_task} is set!**
+
+If `{resume_task}` is set:
+
+1. Search for matching task in `.claude/output/apex/`
+2. If found: Read `00-context.md` to restore state variables
+3. Find last completed step (look for "Status: Complete" markers)
+4. Load next incomplete step
+5. **STOP** - do not continue with fresh init
+
+If no match found: List available tasks and ask user to specify.
+
+### 3. Interactive Mode (if -i flag)
+
+If `{interactive_mode}` = true:
+
+```yaml
+questions:
+  - header: "Configure"
+    question: "Select flags to enable for this workflow:"
+    options:
+      - label: "Auto mode (-a)"
+        description: "Skip all confirmations, use recommended options"
+      - label: "Examine mode (-x)"
+        description: "Include adversarial code review at end"
+      - label: "Save mode (-s)"
+        description: "Save all outputs to .claude/output/apex/"
+      - label: "Test mode (-t)"
+        description: "Include test creation and runner steps"
+      - label: "Economy mode (-e)"
+        description: "No subagents, direct tools only (saves tokens)"
+    multiSelect: true
+```
+
+### 4. Create Output Structure (if save_mode)
+
+**If `{save_mode}` = true:**
+
+1. Create directory: `.claude/output/apex/{task_id}/`
+
+2. Write `00-context.md`:
+
+```markdown
+# APEX Task: {task_id}
+
+**Created:** {timestamp}
+**Task:** {task_description}
+
+## Configuration
+
+| Flag | Value |
+|------|-------|
+| Auto mode | {auto_mode} |
+| Examine mode | {examine_mode} |
+| Save mode | {save_mode} |
+| Test mode | {test_mode} |
+| Economy mode | {economy_mode} |
+
+## User Request
+
+{original user input}
+
+## Acceptance Criteria
+
+_To be defined in step-01-analyze_
+
+## Progress
+
+| Step | Status |
+|------|--------|
+| 00-init | In Progress |
+| 01-analyze | Pending |
+| 02-plan | Pending |
+| 03-execute | Pending |
+| 04-validate | Pending |
+| 05-examine | {examine_mode ? "Pending" : "Skip"} |
+| 06-resolve | {examine_mode ? "Pending" : "Skip"} |
+| 07-tests | {test_mode ? "Pending" : "Skip"} |
+| 08-run-tests | {test_mode ? "Pending" : "Skip"} |
+```
+
+3. Mark 00-init as Complete in the Progress table
+
+### 5. Show Summary and Proceed
+
+**Always show COMPACT summary:**
+
+```
+APEX: {task_description}
+
+| Variable | Value |
+|----------|-------|
+| {task_id} | 01-kebab-name |
+| {auto_mode} | true/false |
+| {examine_mode} | true/false |
+| {save_mode} | true/false |
+| {test_mode} | true/false |
+| {economy_mode} | true/false |
+
+-> Analyzing...
+```
+
+**Then proceed directly to step-01-analyze.md**
+
+---
+
+## SUCCESS METRICS:
+
+- All flags correctly parsed
+- Output is COMPACT (one table, no verbose logs)
+- Variables shown with `{brackets}` notation
+- Proceeded to step-01 immediately after summary
+- Output folder created with 00-context.md (if save_mode)
+
+## NEXT STEP:
+
+After showing initialization summary, always proceed directly to `./step-01-analyze.md`

package/templates/skills/apex/steps/step-01-analyze.md

@@ -0,0 +1,210 @@
+---
+name: step-01-analyze
+description: Pure context gathering - explore codebase to understand WHAT EXISTS
+next_step: steps/step-02-plan.md
+---
+
+# Step 1: Analyze (Context Gathering)
+
+## MANDATORY EXECUTION RULES:
+
+- NEVER plan or design solutions - that's step 2
+- NEVER create todos or implementation tasks
+- NEVER decide HOW to implement anything
+- ALWAYS focus on discovering WHAT EXISTS
+- ALWAYS report findings with file paths and line numbers
+- YOU ARE AN EXPLORER, not a planner
+- FORBIDDEN to suggest implementations or approaches
+
+## YOUR TASK:
+
+Gather ALL relevant context about WHAT CURRENTLY EXISTS in the codebase related to the task.
+
+---
+
+<available_state>
+From step-00-init:
+
+| Variable | Description |
+|----------|-------------|
+| `{task_description}` | What to implement |
+| `{task_id}` | Kebab-case identifier |
+| `{auto_mode}` | Skip confirmations |
+| `{examine_mode}` | Auto-proceed to review |
+| `{save_mode}` | Save outputs to files |
+| `{test_mode}` | Include test steps |
+| `{economy_mode}` | No subagents, direct tools |
+| `{output_dir}` | Path to output (if save_mode) |
+</available_state>
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Extract Search Keywords
+
+From the task description, identify:
+- **Domain terms**: auth, user, payment, etc.
+- **Technical terms**: API, route, component, etc.
+- **Action hints**: create, update, fix, add, etc.
+
+These keywords guide exploration - NOT planning.
+
+### 2. Explore Codebase
+
+**If `{economy_mode}` = true:**
+
+Use direct tools only:
+1. Glob to find files: `**/*{keyword}*`
+2. Grep to search content in likely locations
+3. Read the most relevant 3-5 files
+4. Skip web research unless stuck
+
+**If `{economy_mode}` = false:**
+
+Launch parallel exploration agents in a SINGLE message:
+
+**Agent 1: Codebase Exploration** (`explore-codebase`)
+```
+Find existing code related to: {task_description}
+
+Report ONLY what exists:
+1. Files that contain related code (with paths and line numbers)
+2. Existing patterns used for similar features
+3. Utility functions that might be relevant
+4. How similar features are currently structured
+5. Test file locations and patterns
+
+DO NOT suggest what to build. Just report what's there.
+```
+
+**Agent 2: Documentation Research** (`explore-docs`)
+```
+Research documentation for libraries used in: {task_description}
+
+Find:
+1. How the relevant libraries/frameworks work
+2. API documentation for tools being used
+3. Best practices from official docs
+```
+
+**Agent 3: Web Research** (`websearch`)
+```
+Search for context about: {task_description}
+
+Find:
+1. How this is typically implemented
+2. Common patterns and approaches
+3. Known pitfalls or gotchas
+```
+
+### 3. Synthesize Findings
+
+Combine results into structured context:
+
+```markdown
+## Codebase Context
+
+### Related Files Found
+| File | Lines | Contains |
+|------|-------|----------|
+| `src/auth/login.ts` | 1-150 | Existing login implementation |
+| `src/utils/validate.ts` | 20-45 | Email validation helper |
+
+### Patterns Observed
+- **Route pattern**: Uses Next.js App Router with `route.ts`
+- **Validation**: Uses zod schemas in `schemas/` folder
+- **Error handling**: Throws custom ApiError classes
+
+### Utilities Available
+- `src/lib/auth.ts` - JWT sign/verify functions
+- `src/lib/db.ts` - Prisma client instance
+
+### Similar Implementations
+- `src/auth/login.ts:42` - Login flow (reference for patterns)
+
+### Test Patterns
+- Tests in `__tests__/` folders
+- Uses vitest with testing-library
+
+## Documentation Insights
+
+### Libraries Used
+- **jose**: JWT library - uses `SignJWT` class
+- **prisma**: ORM - uses `prisma.user.create()` pattern
+
+## Research Findings
+
+### Common Approaches
+- Registration: validate -> hash -> create -> issue token
+- Use httpOnly cookies for tokens
+```
+
+### 4. Infer Acceptance Criteria
+
+Based on task and context, infer success criteria:
+
+```markdown
+## Inferred Acceptance Criteria
+
+Based on "{task_description}" and existing patterns:
+
+- [ ] AC1: [specific measurable outcome]
+- [ ] AC2: [specific measurable outcome]
+- [ ] AC3: [specific measurable outcome]
+
+_These will be refined in the planning step._
+```
+
+### 5. Save Output (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Write findings to `{output_dir}/01-analyze.md`:
+- Include all sections above
+- Add timestamp at the end
+- Update 00-context.md Progress table: 01-analyze -> Complete
+
+### 6. Present Context Summary
+
+```
+**Context Gathering Complete**
+
+**Files analyzed:** {count}
+**Patterns identified:** {count}
+**Utilities found:** {count}
+
+**Key findings:**
+- {summary of relevant files}
+- {patterns that will guide implementation}
+
+-> Proceeding to planning phase...
+```
+
+**Always proceed directly to step-02-plan.md**
+
+---
+
+## SUCCESS METRICS:
+
+- Related files identified with paths and line numbers
+- Existing patterns documented with specific examples
+- Available utilities noted
+- Dependencies listed
+- Acceptance criteria inferred
+- NO planning or implementation decisions made
+
+## FAILURE MODES:
+
+- Starting to plan or design (that's step 2!)
+- Suggesting implementations or approaches
+- Missing obvious related files
+- Not documenting patterns with file:line references
+- Launching agents sequentially instead of parallel
+- Using subagents when economy_mode is true
+
+---
+
+## NEXT STEP:
+
+Always proceed directly to `./step-02-plan.md` after presenting context summary.