@vpxa/aikit 0.1.20 → 0.1.22

package/scaffold/general/skills/aikit/SKILL.md

@@ -43,7 +43,7 @@ core → store → embeddings → chunker → indexer → analyzers → tools
 ### Start (do ALL)
 ```
 flow_status({})                                                # Check/resume active flow FIRST
-# If flow active → flow_read_skill({ step }) → follow skill instructions
+# If flow active → flow_read_instruction({ step }) → follow step instructions
 status({})                                                     # Check AI Kit health + onboard state
 # If onboard not run → onboard({ path: "." })                 # First-time codebase analysis
 flow_list({})                                                  # See available flows
@@ -189,7 +189,7 @@ Lane actions: `create` (copy files to lane), `list`, `status` (modified/added/de
 | `flow_start` | `aikit flow start` | Start a named flow |
 | `flow_step` | `aikit flow step` | Advance, skip, or redo the current step |
 | `flow_status` | `aikit flow status` | Check if a flow is active and view the current step |
-| `flow_read_skill` | `aikit flow read-skill` | Read the current step's skill file content directly |
+| `flow_read_instruction` | `aikit flow read-instruction` | Read the current step's instruction file content directly |
 | `flow_reset` | `aikit flow reset` | Clear flow state to start over |
 
 ### Presentation (1)
@@ -219,8 +219,8 @@ Flows are multi-step guided workflows that structure complex tasks. Each step ha
 flow_list()                          # See available flows
 flow_info({ flow: "aikit:basic" })   # View steps, skills, agents
 flow_start({ flow: "aikit:basic" })  # Start — sets current step to first
-flow_read_skill({ step: "assess" })  # Read current step's skill instructions
-# ... do the work described in the skill ...
+flow_read_instruction({ step: "assess" })  # Read current step's instructions
+# ... do the work described in the instruction ...
 flow_step({ action: "next" })        # Advance to next step
 flow_step({ action: "skip" })        # Skip current step
 flow_step({ action: "redo" })        # Redo current step
@@ -241,14 +241,14 @@ artifacts_dir: .spec
 steps:
   - id: design
     name: Design
-    skill: skills/design/SKILL.md
+    instruction: steps/design/README.md
     description: "Create the design document"
     produces: [design.md]
     requires: []
     agents: [Planner]
   - id: implement
     name: Implement
-    skill: skills/implement/SKILL.md
+    instruction: steps/implement/README.md
     description: "Implement the design"
     produces: [code]
     requires: [design]
@@ -271,7 +271,7 @@ install: []
 ### Agent-Flow Integration
 
 - All code agents have a "Flows" section instructing them to check `flow_status()` first
-- If a flow is active, the agent follows the current step's skill via `flow_read_skill()`
+- If a flow is active, the agent follows the current step's instruction via `flow_read_instruction()`
 - After completing a step's work, advance with `flow_step({ action: "next" })`
 - The **Orchestrator** selects and starts flows; other agents follow them
 - The **Orchestrator** specifies `aikit` skill loading — all agents should load `aikit` skill to access flow tools
@@ -528,7 +528,7 @@ Flows are structured multi-step workflows that guide agents through complex task
 | `flow_info` | Get flow details including steps and skill paths |
 | `flow_start` | Start a named flow |
 | `flow_step` | Advance: `next`, `skip`, or `redo` current step |
-| `flow_read_skill` | Read the current step's skill file content directly |
+| `flow_read_instruction` | Read the current step's instruction file content directly |
 | `flow_reset` | Clear flow state to start over |
 
 ### Flow Selection
@@ -545,7 +545,7 @@ Flows are structured multi-step workflows that guide agents through complex task
 ### Flow Lifecycle
 
 1. **Start**: `flow_list({})` → choose flow → `flow_start({ flow: "<name>" })`
-2. **Each step**: `flow_read_skill({ step: "<name>" })` → follow skill instructions → complete work
+2. **Each step**: `flow_read_instruction({ step: "<name>" })` → follow step instructions → complete work
 3. **Advance**: `flow_step({ action: "next" })` → repeat from step 2
-4. **Resume**: `flow_status({})` → if active, `flow_read_skill` for current step → continue
+4. **Resume**: `flow_status({})` → if active, `flow_read_instruction` for current step → continue
 5. **Reset**: `flow_reset({})` if you need to start over

package/scaffold/general/skills/brainstorming/SKILL.md

@@ -90,7 +90,7 @@ digraph brainstorming_simple {
 
 1. **Explore project context** — check files, docs, recent commits
 2. **Assess scope** — if multiple independent subsystems, decompose before detailing (see below)
-3. **Offer visual companion** (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. See `visual-companion.md`.
+3. **Offer visual presentation support** (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. Use `present({ format: "html" })` to display brainstorming results as a rich visual dashboard.
 4. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
 5. **Propose 2-3 approaches via Decision Protocol** — launch ALL 4 Researcher variants in parallel to independently generate approaches. Synthesize their output into deduplicated options with trade-offs and your recommendation. Present agreements and disagreements to the user. *(See "Decision Protocol Integration" below.)*
 6. **Present design** — in sections scaled to their complexity, get user approval after each section
@@ -122,7 +122,7 @@ digraph brainstorming_advanced {
     "Assess scope" [shape=diamond];
     "Decompose into sub-projects" [shape=box];
     "Visual questions ahead?" [shape=diamond];
-    "Offer Visual Companion\n(own message)" [shape=box];
+    "Offer Visual Presentation\n(own message)" [shape=box];
     "Ask clarifying questions" [shape=box];
     "Decision Protocol:\n4 Researchers in parallel" [shape=box, style=bold];
     "Synthesize approaches" [shape=box];
@@ -138,9 +138,9 @@ digraph brainstorming_advanced {
     "Assess scope" -> "Decompose into sub-projects" [label="too large"];
     "Assess scope" -> "Visual questions ahead?" [label="right-sized"];
     "Decompose into sub-projects" -> "Visual questions ahead?" [label="first sub-project"];
-    "Visual questions ahead?" -> "Offer Visual Companion\n(own message)" [label="yes"];
+    "Visual questions ahead?" -> "Offer Visual Presentation\n(own message)" [label="yes"];
     "Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
-    "Offer Visual Companion\n(own message)" -> "Ask clarifying questions";
+    "Offer Visual Presentation\n(own message)" -> "Ask clarifying questions";
     "Ask clarifying questions" -> "Decision Protocol:\n4 Researchers in parallel";
     "Decision Protocol:\n4 Researchers in parallel" -> "Synthesize approaches";
     "Synthesize approaches" -> "Present design sections";
@@ -242,18 +242,16 @@ Wait for the user's response. If they request changes, make them and re-run the
 - **Incremental validation** — Present design, get approval before moving on
 - **Be flexible** — Go back and clarify when something doesn't make sense
 
-## Visual Companion (Advanced Mode Only)
+## Visual Presentation Support (Advanced Mode Only)
 
-A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.
+Use the `present` MCP tool for showing mockups, diagrams, and visual options during brainstorming. It is available as a tool, not a separate mode. Choosing this means you can present rich visual output when it helps; it does NOT mean every question should become visual.
 
-**Offering the companion:** When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:
-> "Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. The browser opens automatically when I start the visual companion. This feature is still new and can be token-intensive. Want to try it?"
+**Offering visual presentation:** When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:
+> "Some of what we're working on might be easier to explain visually. I can use `present({ format: \"html\" })` to show mockups, diagrams, comparisons, and other visuals as we go. Want me to use that when helpful?"
 
 **This offer MUST be its own message.** Do not combine it with clarifying questions, context summaries, or any other content. Wait for the user's response before continuing. If they decline, proceed with text-only brainstorming.
 
-**Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: **would the user understand this better by seeing it than reading it?**
+**Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use visual output or plain chat. The test: **would the user understand this better by seeing it than reading it?**
 
-- **Use the browser** for visual content — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
-- **Use the terminal** for text content — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions
-
-If they agree to the companion, read `visual-companion.md` for the detailed setup and usage guide.
+- **Use `present({ format: "html" })`** for visual content — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
+- **Use regular chat** for text content — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions

package/scaffold/general/skills/c4-architecture/SKILL.md

@@ -12,6 +12,7 @@ Generate software architecture documentation using C4 model diagrams in Mermaid
 1. **Understand scope** - Determine which C4 level(s) are needed based on audience
 2. **Analyze codebase** - Explore the system to identify components, containers, and relationships
 3. **Generate diagrams** - Create Mermaid C4 diagrams at appropriate abstraction levels
+  > **Tip:** Use `present({ format: "html" })` to render diagrams as interactive visual output, rather than raw Mermaid code blocks. This provides a better viewing experience for stakeholders.
 4. **Document** - Write diagrams to markdown files with explanatory context
 
 ## C4 Diagram Levels

package/scaffold/general/skills/requirements-clarity/SKILL.md

@@ -70,7 +70,7 @@ When invoked, detect vague requirements:
 1. Parse and understand core requirement
 2. Generate feature name (kebab-case format)
 3. Determine document version (default `1.0` unless user specifies otherwise)
-4. Ensure `./docs/prds/` exists for PRD output
+4. Ensure `.spec/{feature_name}/` exists for PRD output
 5. Perform initial clarity assessment (0-100)
 
 **Assessment Rubric**:
@@ -85,6 +85,8 @@ Technical Specificity: /25 points
 - Integration points identified: 8 pts
 - Constraints specified: 9 pts
 
+
+If you present this rubric or a requirements scorecard to the user, use `present({ format: 'html' })` to display a rich dashboard when visual formatting would help.
 Implementation Completeness: /25 points
 - Edge cases considered: 8 pts
 - Error handling mentioned: 9 pts
@@ -191,9 +193,9 @@ Once clarity score ≥ 90, generate comprehensive PRD.
 
 **Output File**:
 
-1. **Final PRD**: `./docs/prds/{feature_name}-v{version}-prd.md`
+1. **Final PRD**: `.spec/{feature_name}/requirements.md`
 
-Use the `Write` tool to create or update this file. Derive `{version}` from the document version recorded in the PRD (default `1.0`).
+Use `create_file` to save this file. Derive `{version}` from the document version recorded in the PRD (default `1.0`).
 
 ## PRD Document Structure
 

package/scaffold/general/skills/session-handoff/SKILL.md

@@ -20,6 +20,8 @@ Determine which mode applies:
 **Proactive suggestion?** After substantial work (5+ file edits, complex debugging, major decisions), suggest:
 > "We've made significant progress. Consider creating a handoff document to preserve this context for future sessions. Say 'create handoff' when ready."
 
+> **aikit Integration:** If the project uses the aikit MCP server, complement file-based handoffs with `remember({ title: "Session checkpoint: ...", content: "...", category: "conventions" })` to persist key decisions in the knowledge base. Use `search({ query: "SESSION CHECKPOINT" })` at session start to retrieve past checkpoints.
+
 ## CREATE Workflow
 
 ### Step 1: Generate Scaffold

package/scaffold/general/skills/brainstorming/scripts/frame-template.html

@@ -1,365 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>Brainstorming</title>
-<style>
-  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
-
-  :root {
-    --bg: #0d1117;
-    --surface: #161b22;
-    --border: #30363d;
-    --text: #e6edf3;
-    --text-muted: #8b949e;
-    --accent: #58a6ff;
-    --accent-glow: rgba(88, 166, 255, 0.15);
-    --success: #3fb950;
-    --radius: 8px;
-  }
-
-  body {
-    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
-    background: var(--bg);
-    color: var(--text);
-    line-height: 1.6;
-    min-height: 100vh;
-  }
-
-  .frame-header {
-    padding: 16px 24px;
-    border-bottom: 1px solid var(--border);
-    display: flex;
-    align-items: center;
-    gap: 12px;
-  }
-  .frame-header .logo {
-    font-size: 14px;
-    font-weight: 600;
-    color: var(--text-muted);
-    letter-spacing: 0.5px;
-    text-transform: uppercase;
-  }
-
-  .frame-content {
-    max-width: 960px;
-    margin: 0 auto;
-    padding: 32px 24px;
-  }
-
-  /* Selection indicator bar */
-  #selection-indicator {
-    position: fixed;
-    bottom: 0;
-    left: 0;
-    right: 0;
-    background: var(--surface);
-    border-top: 1px solid var(--border);
-    padding: 12px 24px;
-    display: none;
-    align-items: center;
-    justify-content: center;
-    gap: 8px;
-    font-size: 14px;
-    color: var(--accent);
-    z-index: 100;
-  }
-  #selection-indicator.visible { display: flex; }
-  #selection-indicator .check { font-size: 18px; }
-
-  /* Typography */
-  h2 {
-    font-size: 24px;
-    font-weight: 600;
-    margin-bottom: 8px;
-    color: var(--text);
-  }
-  h3 {
-    font-size: 18px;
-    font-weight: 600;
-    margin-bottom: 4px;
-    color: var(--text);
-  }
-  h4 {
-    font-size: 14px;
-    font-weight: 600;
-    margin-bottom: 8px;
-    color: var(--text);
-  }
-  .subtitle {
-    font-size: 16px;
-    color: var(--text-muted);
-    margin-bottom: 24px;
-  }
-  .section {
-    margin-bottom: 32px;
-  }
-  .label {
-    font-size: 11px;
-    font-weight: 600;
-    text-transform: uppercase;
-    letter-spacing: 0.8px;
-    color: var(--text-muted);
-    margin-bottom: 8px;
-  }
-
-  /* Options (A/B/C choices) */
-  .options {
-    display: flex;
-    flex-direction: column;
-    gap: 12px;
-    margin: 16px 0;
-  }
-  .option {
-    display: flex;
-    align-items: flex-start;
-    gap: 16px;
-    padding: 16px 20px;
-    background: var(--surface);
-    border: 2px solid var(--border);
-    border-radius: var(--radius);
-    cursor: pointer;
-    transition: border-color 0.15s, background 0.15s;
-  }
-  .option:hover {
-    border-color: var(--accent);
-    background: var(--accent-glow);
-  }
-  .option.selected {
-    border-color: var(--accent);
-    background: var(--accent-glow);
-  }
-  .option .letter {
-    flex-shrink: 0;
-    width: 32px;
-    height: 32px;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    border-radius: 50%;
-    background: var(--border);
-    font-weight: 700;
-    font-size: 14px;
-    color: var(--text-muted);
-    transition: background 0.15s, color 0.15s;
-  }
-  .option.selected .letter {
-    background: var(--accent);
-    color: var(--bg);
-  }
-  .option .content { flex: 1; }
-  .option .content p {
-    color: var(--text-muted);
-    font-size: 14px;
-    margin-top: 4px;
-  }
-
-  /* Cards (visual designs) */
-  .cards {
-    display: grid;
-    grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
-    gap: 16px;
-    margin: 16px 0;
-  }
-  .card {
-    background: var(--surface);
-    border: 2px solid var(--border);
-    border-radius: var(--radius);
-    overflow: hidden;
-    cursor: pointer;
-    transition: border-color 0.15s, transform 0.15s;
-  }
-  .card:hover {
-    border-color: var(--accent);
-    transform: translateY(-2px);
-  }
-  .card.selected {
-    border-color: var(--accent);
-  }
-  .card-image {
-    padding: 20px;
-    background: rgba(255,255,255,0.02);
-    min-height: 180px;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-  }
-  .card-body {
-    padding: 16px;
-  }
-  .card-body p {
-    color: var(--text-muted);
-    font-size: 14px;
-    margin-top: 4px;
-  }
-
-  /* Mockup container */
-  .mockup {
-    background: var(--surface);
-    border: 1px solid var(--border);
-    border-radius: var(--radius);
-    overflow: hidden;
-    margin: 16px 0;
-  }
-  .mockup-header {
-    padding: 8px 16px;
-    font-size: 12px;
-    font-weight: 600;
-    color: var(--text-muted);
-    background: rgba(255,255,255,0.03);
-    border-bottom: 1px solid var(--border);
-  }
-  .mockup-body {
-    padding: 20px;
-  }
-
-  /* Split view */
-  .split {
-    display: grid;
-    grid-template-columns: 1fr 1fr;
-    gap: 16px;
-    margin: 16px 0;
-  }
-  @media (max-width: 700px) {
-    .split { grid-template-columns: 1fr; }
-  }
-
-  /* Pros/Cons */
-  .pros-cons {
-    display: grid;
-    grid-template-columns: 1fr 1fr;
-    gap: 16px;
-    margin: 16px 0;
-  }
-  .pros, .cons {
-    padding: 16px;
-    border-radius: var(--radius);
-  }
-  .pros {
-    background: rgba(63, 185, 80, 0.08);
-    border: 1px solid rgba(63, 185, 80, 0.3);
-  }
-  .cons {
-    background: rgba(248, 81, 73, 0.08);
-    border: 1px solid rgba(248, 81, 73, 0.3);
-  }
-  .pros h4 { color: #3fb950; }
-  .cons h4 { color: #f85149; }
-  .pros-cons ul {
-    list-style: none;
-    padding: 0;
-  }
-  .pros-cons li {
-    padding: 4px 0;
-    font-size: 14px;
-    color: var(--text-muted);
-  }
-  .pros-cons li::before {
-    margin-right: 8px;
-    font-weight: 600;
-  }
-  .pros li::before { content: '+'; color: #3fb950; }
-  .cons li::before { content: '−'; color: #f85149; }
-
-  /* Mock elements (wireframe building blocks) */
-  .mock-nav {
-    background: var(--surface);
-    border: 1px solid var(--border);
-    border-radius: var(--radius);
-    padding: 12px 20px;
-    font-size: 14px;
-    color: var(--text-muted);
-    margin-bottom: 12px;
-  }
-  .mock-sidebar {
-    width: 200px;
-    flex-shrink: 0;
-    background: var(--surface);
-    border: 1px solid var(--border);
-    border-radius: var(--radius);
-    padding: 16px;
-    font-size: 13px;
-    color: var(--text-muted);
-    margin-right: 12px;
-  }
-  .mock-content {
-    flex: 1;
-    background: var(--surface);
-    border: 1px solid var(--border);
-    border-radius: var(--radius);
-    padding: 20px;
-    font-size: 14px;
-    color: var(--text-muted);
-    min-height: 200px;
-  }
-  .mock-button {
-    padding: 8px 20px;
-    background: var(--accent);
-    color: var(--bg);
-    border: none;
-    border-radius: 6px;
-    font-size: 14px;
-    font-weight: 600;
-    cursor: pointer;
-  }
-  .mock-button:hover { opacity: 0.9; }
-  .mock-input {
-    padding: 8px 12px;
-    background: var(--surface);
-    border: 1px solid var(--border);
-    border-radius: 6px;
-    color: var(--text);
-    font-size: 14px;
-    width: 100%;
-    max-width: 300px;
-  }
-  .mock-input::placeholder { color: var(--text-muted); }
-  .placeholder {
-    background: rgba(255,255,255,0.03);
-    border: 1px dashed var(--border);
-    border-radius: var(--radius);
-    padding: 40px 20px;
-    text-align: center;
-    color: var(--text-muted);
-    font-size: 14px;
-  }
-
-  /* General list styling inside content */
-  .frame-content ul, .frame-content ol {
-    padding-left: 20px;
-    margin: 8px 0;
-  }
-  .frame-content li {
-    margin: 4px 0;
-    color: var(--text-muted);
-    font-size: 14px;
-  }
-  .frame-content p {
-    margin: 8px 0;
-  }
-  .frame-content a {
-    color: var(--accent);
-    text-decoration: none;
-  }
-  .frame-content a:hover { text-decoration: underline; }
-
-</style>
-</head>
-<body>
-  <div class="frame-header">
-    <span class="logo">Brainstorming</span>
-  </div>
-  <div class="frame-content">
-    <!-- CONTENT -->
-  </div>
-  <div id="selection-indicator">
-    <span class="check">✓</span>
-    <span id="selection-text">Selected</span>
-  </div>
-  <script>
-    const BRAINSTORM_DIR = __BRAINSTORM_DIR__;
-    <!-- HELPER_SCRIPT -->
-  </script>
-</body>
-</html>