ostacky 0.5.5 → 0.5.7

package/assets/skills/openspec-apply-change/SKILL.md

@@ -15,16 +15,25 @@ Implement tasks from an OpenSpec change.
 
 **Steps**
 
-1. **Select the change**
+1. **Check Engram for past implementation patterns**
+
+   Before implementing, `engram_mem_search` with keywords from the change name and affected modules. Look for:
+   - Similar changes implemented before (approaches that worked or failed)
+   - Known gotchas or edge cases in related areas
+   - Model selection patterns for similar task complexity
+
+   Surface relevant findings to inform implementation decisions.
+
+2. **Select the change**
 
    If a name is provided, use it. Otherwise:
    - Infer from conversation context if the user mentioned a change
    - Auto-select if only one active change exists
-   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+   - If ambiguous, run `openspec list --json` to get available changes and use the **question tool** to let the user select. After calling `question`, STOP and wait for the answer.
 
    Always announce: "Using change: <name>" and how to override (e.g., `/opsx-apply <other>`).
 
-2. **Check status to understand the schema**
+3. **Check status to understand the schema**
    ```bash
    openspec status --change "<name>" --json
    ```
@@ -32,7 +41,7 @@ Implement tasks from an OpenSpec change.
    - `schemaName`: The workflow being used (e.g., "spec-driven")
    - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
 
-3. **Get apply instructions**
+4. **Get apply instructions**
 
    ```bash
    openspec instructions apply --change "<name>" --json
@@ -49,14 +58,14 @@ Implement tasks from an OpenSpec change.
    - If `state: "all_done"`: congratulate, suggest archive
    - Otherwise: proceed to implementation
 
-4. **Read context files**
+5. **Read context files**
 
-   Read every file path listed under `contextFiles` from the apply instructions output.
+   Use **CodeGraph** (`codegraph_explore`) to understand the code structure before reading files directly. Then read every file path listed under `contextFiles` from the apply instructions output.
    The files depend on the schema being used:
    - **spec-driven**: proposal, specs, design, tasks
    - Other schemas: follow the contextFiles from CLI output
 
-5. **Show current progress**
+6. **Show current progress**
 
    Display:
    - Schema being used
@@ -64,7 +73,7 @@ Implement tasks from an OpenSpec change.
    - Remaining tasks overview
    - Dynamic instruction from CLI
 
-6. **Implement tasks (loop until done or blocked)**
+7. **Implement tasks (loop until done or blocked)**
 
    For each pending task:
    - Show which task is being worked on
@@ -79,7 +88,7 @@ Implement tasks from an OpenSpec change.
    - Error or blocker encountered → report and wait for guidance
    - User interrupts
 
-7. **On completion or pause, show status**
+8. **On completion or pause, show status**
 
    Display:
    - Tasks completed this session

package/assets/skills/openspec-archive-change/SKILL.md

@@ -17,7 +17,7 @@ Archive a completed change in the experimental workflow.
 
 1. **If no change name provided, prompt for selection**
 
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Run `openspec list --json` to get available changes. Use the **question tool** to let the user select. After calling `question`, STOP and wait for the answer.
 
    Show only active changes (not already archived).
    Include the schema used for each change if available.
@@ -34,7 +34,7 @@ Archive a completed change in the experimental workflow.
 
    **If any artifacts are not `done`:**
    - Display warning listing incomplete artifacts
-   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Use **question tool** to confirm user wants to proceed. After calling `question`, STOP and wait for the answer.
    - Proceed if user confirms
 
 3. **Check task completion status**
@@ -45,7 +45,7 @@ Archive a completed change in the experimental workflow.
 
    **If incomplete tasks found:**
    - Display warning showing count of incomplete tasks
-   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Use **question tool** to confirm user wants to proceed. After calling `question`, STOP and wait for the answer.
    - Proceed if user confirms
 
    **If no tasks file exists:** Proceed without task-related warning.

package/assets/skills/openspec-propose/SKILL.md

@@ -24,22 +24,24 @@ When ready to implement, run /opsx-apply
 
 **Steps**
 
-1. **If no clear input provided, ask what they want to build**
+1. **Check Engram for similar changes** — `engram_mem_search` with keywords from the user's description. If a similar change was proposed or implemented before, surface it to the user. They may want to extend the existing work instead of starting fresh.
 
-   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+2. **If no clear input provided, ask what they want to build**
+
+   Use the **question tool** (open-ended, no preset options) to ask:
    > "What change do you want to work on? Describe what you want to build or fix."
 
    From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
 
-   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build. **IMPORTANT**: After calling `question`, STOP. Do not generate more text or execute tools.
 
-2. **Create the change directory**
+3. **Create the change directory**
    ```bash
    openspec new change "<name>"
    ```
    This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
 
-3. **Get the artifact build order**
+4. **Get the artifact build order**
    ```bash
    openspec status --change "<name>" --json
    ```
@@ -47,7 +49,7 @@ When ready to implement, run /opsx-apply
    - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
    - `artifacts`: list of all artifacts with their status and dependencies
 
-4. **Create artifacts in sequence until apply-ready**
+5. **Create artifacts in sequence until apply-ready**
 
    Use the **TodoWrite tool** to track progress through the artifacts.
 
@@ -76,10 +78,10 @@ When ready to implement, run /opsx-apply
       - Stop when all `applyRequires` artifacts are done
 
    c. **If an artifact requires user input** (unclear context):
-      - Use **AskUserQuestion tool** to clarify
+      - Use **question tool** to clarify, then STOP and wait for the answer
       - Then continue with creation
 
-5. **Show final status**
+6. **Show final status**
    ```bash
    openspec status --change "<name>"
    ```

package/assets/skills/review/SKILL.md

@@ -52,10 +52,12 @@ After obtaining the diff, if it is empty, inform the user that there are no chan
 
 Before analyzing the diff:
 
-1. **Read changed files in full** - Do not review a diff in isolation. Read each modified file to understand the surrounding code, imports, types, and control flow.
-2. **Identify the tech stack** - Note languages, frameworks, and libraries in use. This affects what patterns are risky.
-3. **Check for related test files** - For each changed source file, look for corresponding test files. Note whether tests were updated alongside the changes.
-4. **Check for configuration changes** - If config files changed (env, CI, package.json, tsconfig, etc.), pay extra attention to side effects.
+1. **Follow Core Instructions** — `ostacky.md` Core Instructions section for CodeGraph usage patterns. Use `codegraph_explore` to understand the code structure before reading files directly.
+2. **Use CodeGraph for code understanding** — `codegraph_explore` on the changed symbols gives you call paths, blast radius, and related code in ONE call. Only `Read` files for details CodeGraph didn't cover.
+3. **Read changed files for full context** — After CodeGraph exploration, read each modified file to understand the surrounding code, imports, types, and control flow.
+4. **Identify the tech stack** — Note languages, frameworks, and libraries in use. This affects what patterns are risky.
+5. **Check for related test files** — For each changed source file, look for corresponding test files. Note whether tests were updated alongside the changes.
+6. **Check for configuration changes** — If config files changed (env, CI, package.json, tsconfig, etc.), pay extra attention to side effects.
 
 </gather_context>
 
@@ -133,7 +135,7 @@ Severity levels:
 
 <critical_rules>
 
-1. **READ THE FULL FILE**: Never review a diff without reading the complete source file for context
+1. **FOLLOW CORE INSTRUCTIONS** — Use CodeGraph for code understanding before reading files. See `ostacky.md` Core Instructions section.
 2. **NO FALSE ALARMS**: Only report issues you can explain concretely. Do not report vague concerns
 3. **PRIORITIZE**: Lead with the most severe findings. Do not bury critical issues under style nits
 4. **BE SPECIFIC**: Include file paths, line numbers, and code references for every finding

package/assets/skills/subagent-driven-development/SKILL.md

@@ -10,6 +10,7 @@ description: Use when Ostacky has confirmed subagent-driven execution mode and d
 2. Presented evidence and recommendation to the user
 3. Received explicit user confirmation for subagent-driven mode
 4. Called `controller.consumeExecutionDecision({ mode: "SUBAGENT_DRIVEN" })`
+5. Checked Engram (`engram_mem_search`) for past subagent execution patterns on similar changes — if a previous approach failed, avoid repeating it
 
 Subagents are execution-only. They never create routing decisions, re-analyze execution mode, or duplicate discovery that the coordinator already resolved.
 
@@ -47,6 +48,18 @@ digraph when_to_use {
 - Two-stage review after each task: spec compliance first, then code quality
 - Faster iteration (no human-in-loop between tasks)
 
+## Context Gathering for Subagents
+
+**Follow Core Instructions** — `ostacky.md` Core Instructions section for CodeGraph usage patterns. Do NOT duplicate those instructions here.
+
+When constructing the context package for each subagent:
+
+1. Use `codegraph_explore` to get the verbatim source of relevant symbols, their call paths, and blast radius — in ONE call.
+2. Only use `Read` for files or details CodeGraph didn't cover.
+3. Include the CodeGraph output in the subagent's context package so they have structural understanding without needing to re-explore.
+
+**Why this matters:** Subagents have limited context. CodeGraph gives them more accurate information in fewer tokens than they'd consume re-reading files themselves.
+
 ## The Process
 
 ```dot
@@ -256,6 +269,7 @@ Done!
 - Let implementer self-review replace actual review (both are needed)
 - **Start code quality review before spec compliance is ✅** (wrong order)
 - Move to next task while either review has open issues
+- **Use `Bash` with `rg`/`grep` for code search** — follow Core Instructions in `ostacky.md`
 
 **If subagent asks questions:**
 - Answer clearly and completely

package/assets/skills/thinking/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: thinking
+description: "Thinking partner for exploring ideas, investigating problems, and designing solutions. Two modes: creative-design (structured, produces design doc) and open-explore (unstructured, no mandatory output). Use when the user wants to think through something, brainstorm, explore an idea, or design a solution before or during a change."
+---
+
+# Thinking
+
+A thinking partner that adapts to what the user needs: structured design when they're building something, open exploration when they're investigating or clarifying.
+
+**Follow Core Instructions** — `ostacky.md` Core Instructions section for CodeGraph and Engram usage patterns.
+
+---
+
+## Mode Detection
+
+| Signal | Mode |
+|--------|------|
+| "design", "build", "create", "add feature", "implement" | **creative-design** |
+| "explore", "investigate", "think through", "what if", "how does" | **open-explore** |
+| "brainstorm", "ideate", "propose approach" | **creative-design** |
+| "check", "understand", "review existing" | **open-explore** |
+| Unclear | Ask with **question** tool: "¿Querés diseñar algo nuevo o explorar/entender algo existente?" |
+
+---
+
+## Mode 1: creative-design
+
+Turn ideas into fully formed designs through collaborative dialogue.
+
+### HARD-GATE
+
+Do NOT invoke any implementation skill, write any code, or scaffold any project until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+
+### Process
+
+1. **Check Engram** — `engram_mem_search` with keywords from the user's idea. Surface any prior design decisions or similar proposals.
+2. **Explore via CodeGraph** — `codegraph_explore` on the affected area. Only `Read` files CodeGraph didn't cover.
+3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
+4. **Propose 2-3 approaches** — with trade-offs and your recommendation
+5. **Present design** — in sections scaled to complexity, get user approval after each section
+6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
+7. **Spec self-review** — check for placeholders, contradictions, ambiguity, scope
+8. **User reviews spec** — ask user to review before proceeding
+9. **Save to Engram** — `engram_mem_save` with the design decision and tradeoffs
+10. **Transition** — based on routing decision (see Transition Rules below)
+
+### Transition Rules
+
+The next step depends on how the change was routed by Ostacky:
+
+| Routing | Next Skill | When |
+|---------|------------|------|
+| **DIRECT** (Level 0/0+1) | `writing-plans` | Small changes, no OpenSpec |
+| **SPEC** (Level 1+) | `openspec-propose` | Complex changes requiring OpenSpec artifacts |
+
+If you're unsure about routing, ask Ostacky or check the controller state.
+
+**Terminal state:** Invoke the appropriate next skill. Do NOT invoke implementation skills directly.
+
+### Design Principles
+
+- **One question at a time** — Don't overwhelm
+- **Multiple choice preferred** — Easier to answer
+- **YAGNI ruthlessly** — Remove unnecessary features
+- **Explore alternatives** — Always propose 2-3 approaches
+- **Incremental validation** — Present design, get approval before moving on
+- **Design for isolation** — Break into smaller units with clear purposes
+
+### Working in Existing Codebases
+
+- Explore current structure before proposing changes. Follow existing patterns.
+- Include targeted improvements where existing code affects the work.
+- Don't propose unrelated refactoring. Stay focused on the goal.
+
+### Spec Self-Review
+
+After writing the spec:
+1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections? Fix them.
+2. **Internal consistency:** Do sections contradict each other?
+3. **Scope check:** Focused enough for a single implementation plan?
+4. **Ambiguity check:** Any requirement interpretable two ways? Pick one.
+
+### User Review Gate
+
+> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
+
+Wait for response. If changes requested, make them and re-review. Only proceed once approved.
+
+---
+
+## Mode 2: open-explore
+
+A stance, not a workflow. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+### What You Might Do
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+Use ASCII diagrams liberally:
+System diagrams, state machines, data flows,
+architecture sketches, dependency graphs,
+comparison tables
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+### OpenSpec Awareness
+
+Check for active changes at start:
+```bash
+openspec list --json
+```
+
+If a change exists and the user mentions it:
+1. Read existing artifacts (`proposal.md`, `design.md`, `tasks.md`)
+2. Reference them naturally in conversation
+3. Offer to capture when decisions are made — don't auto-capture
+
+| Insight Type | Where to Capture |
+|---|---|
+| New requirement | `specs/<capability>/spec.md` |
+| Design decision | `design.md` |
+| Scope change | `proposal.md` |
+| New work | `tasks.md` |
+
+### What You Don't Have To Do
+
+- Follow a script
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+### Ending Discovery
+
+No required ending. Discovery might:
+- **Flow into a proposal:** "Ready to start? I can create a change proposal." → invoke `openspec-propose`
+- **Result in artifact updates:** "Updated design.md with these decisions"
+- **Just provide clarity:** User has what they need, moves on
+- **Continue later:** "We can pick this up anytime"
+
+When things crystallize, summarize:
+```
+## What We Figured Out
+**The problem**: [understanding]
+**The approach**: [if one emerged]
+**Open questions**: [if any]
+**Next steps** (if ready):
+- Create a change proposal (invoke openspec-propose)
+- Keep exploring
+```
+
+But the summary is optional. Sometimes the thinking IS the value.
+
+### Guardrails
+
+- **Don't implement** — Never write code. Creating OpenSpec artifacts is fine.
+- **Don't fake understanding** — Dig deeper if unclear
+- **Don't rush** — Discovery is thinking time, not task time
+- **Don't force structure** — Let patterns emerge naturally
+- **Don't auto-capture** — Offer to save insights, don't just do it
+- **Do visualize** — A good diagram is worth many paragraphs
+- **Do explore the codebase** — Ground discussions in reality
+- **Do question assumptions** — Including your own
+
+---
+
+## Visual Companion
+
+Browser use is text-only by default.
+
+- Only use the browser when the user explicitly asks for browser/visual help.
+- Do not suggest the browser just because it might explain something more clearly.
+- If the user asks for browser/visual help, read `skills/thinking/visual-companion.md` before proceeding.

package/assets/skills/using-git-worktrees/SKILL.md

@@ -211,7 +211,7 @@ Ready to implement auth feature
 ## Integration
 
 **Called by:**
-- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
+- **thinking** (creative-design mode) - REQUIRED when design is approved and implementation follows
 - **subagent-driven-development** - REQUIRED before executing any tasks
 - **executing-plans** - REQUIRED before executing any tasks
 - Any skill needing isolated workspace

package/assets/skills/using-superpowers/SKILL.md

@@ -49,8 +49,8 @@ Skills use Claude Code tool names. Non-CC platforms: see `references/copilot-too
 digraph skill_flow {
     "User message received" [shape=doublecircle];
     "About to EnterPlanMode?" [shape=doublecircle];
-    "Already brainstormed?" [shape=diamond];
-    "Invoke brainstorming skill" [shape=box];
+    "Already thought through?" [shape=diamond];
+    "Invoke thinking skill" [shape=box];
     "Might any skill apply?" [shape=diamond];
     "Invoke Skill tool" [shape=box];
     "Announce: 'Using [skill] to [purpose]'" [shape=box];
@@ -59,10 +59,10 @@ digraph skill_flow {
     "Follow skill exactly" [shape=box];
     "Respond (including clarifications)" [shape=doublecircle];
 
-    "About to EnterPlanMode?" -> "Already brainstormed?";
-    "Already brainstormed?" -> "Invoke brainstorming skill" [label="no"];
-    "Already brainstormed?" -> "Might any skill apply?" [label="yes"];
-    "Invoke brainstorming skill" -> "Might any skill apply?";
+    "About to EnterPlanMode?" -> "Already thought through?";
+    "Already thought through?" -> "Invoke thinking skill" [label="no"];
+    "Already thought through?" -> "Might any skill apply?" [label="yes"];
+    "Invoke thinking skill" -> "Might any skill apply?";
 
     "User message received" -> "Might any skill apply?";
     "Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
@@ -98,10 +98,10 @@ These thoughts mean STOP—you're rationalizing:
 
 When multiple skills could apply, use this order:
 
-1. **Process skills first** (brainstorming, debugging) - these determine HOW to approach the task
+1. **Process skills first** (thinking, debugging) - these determine HOW to approach the task
 2. **Implementation skills second** (frontend-design, mcp-builder) - these guide execution
 
-"Let's build X" → brainstorming first, then implementation skills.
+"Let's build X" → thinking first, then implementation skills.
 "Fix this bug" → debugging first, then domain-specific skills.
 
 ## Skill Types

package/assets/skills/writing-plans/SKILL.md

@@ -18,9 +18,20 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
 **Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
 - (User preferences for plan location override this default)
 
+## Pre-Plan: Check Engram for Past Decisions
+
+Before writing the plan, **consult Engram** to avoid repeating past mistakes:
+
+1. `engram_mem_search` with keywords from the feature name and affected modules
+2. Look for:
+   - Previous plans for similar features (avoid duplicating approaches)
+   - Architecture decisions that affect implementation (design patterns, library choices)
+   - Known gotchas or edge cases discovered in similar work
+3. If relevant findings exist, incorporate them into the plan's context section
+
 ## Scope Check
 
-If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
+If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during thinking (creative-design mode). If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
 
 ## File Structure