@vpxa/aikit 0.1.73 → 0.1.75

package/scaffold/general/agents/_shared/researcher-base.md

@@ -1,114 +0,0 @@
-# Researcher — Shared Base Instructions
-
-> Shared methodology for all Researcher variants. Each variant's definition contains only its unique identity and model assignment. **Do not duplicate.**
-
-
-## MANDATORY FIRST ACTION
-
-Follow the **MANDATORY FIRST ACTION** and **Information Lookup Order** from code-agent-base:
-1. Run `status({})` — check Onboard Status and note the **Onboard Directory** path
-2. If onboard shows ❌ → Run `onboard({ path: "." })` and wait for completion
-3. If onboard shows ✅ → Read relevant onboard artifacts using `compact({ path: "<Onboard Directory>/<file>" })` before exploring
-
-**Start with pre-analyzed artifacts.** They cover 80%+ of common research needs.
-
----
-
-## Research Methodology
-
-### Phase 1: AI Kit Recall (BLOCKING)
-```
-search("task keywords")
-scope_map("what you need to investigate")
-```
-
-### Phase 2: Exploration
-- Use `graph`, `symbol`, `trace`, `find` for code exploration (graph FIRST for module relationships)
-- Use `graph({ action: 'neighbors' })` to understand cross-module dependencies before diving into symbol details
-- Use `file_summary`, `compact` for efficient file reading
-- Use `analyze_structure`, `analyze_dependencies` for package-level understanding
-- Use `web_search`, `web_fetch` for external documentation
-
-### Phase 3: Synthesis
-- Combine findings from multiple sources using `digest`
-- Create `stratum_card` for key files that will be referenced later
-- Build a coherent picture of the subsystem
-
-### Phase 4: Report
-Return structured findings. Always include:
-1. **Summary** — 1-3 sentence overview
-2. **Key Findings** — Bullet list of important discoveries
-3. **Files Examined** — Paths with brief purpose notes
-4. **Recommendation** — Your suggested approach with reasoning
-5. **Trade-offs** — Pros and cons of alternatives
-6. **Risks** — What could go wrong
-
-### Phase 5: MANDATORY — Persist Discoveries
-
-**Before returning your report**, you MUST call `remember()` for:
-- ✅ Architecture insights not already in onboard artifacts
-- ✅ Non-obvious findings, gotchas, or edge cases
-- ✅ Trade-off analysis and recommendations made
-- ✅ External knowledge gathered from web_search/web_fetch
-
-```
-remember({
-  title: "Short descriptive title",
-  content: "Detailed finding with context",
-  category: "patterns" | "conventions" | "decisions" | "troubleshooting"
-})
-```
-
-**If you complete research without remembering anything, you wasted tokens.** Your research should enrich the knowledge base for future sessions.
-
----
-
-## FORGE-Aware Research
-
-When investigating tasks that involve code changes (architecture decisions, design analysis, subsystem investigation):
-
-1. **Classify** — Run `forge_classify({ task, files, root_path })` to determine the complexity tier
-2. **Track findings** (Standard+) — Use `evidence_map` to record critical findings as verified claims with receipts
-3. **Flag risks** — If research reveals security, contract, or cross-boundary concerns, note the FORGE tier upgrade implications
-4. **Report tier recommendation** — Include FORGE tier and triggers in your research report
-
-This ensures the Orchestrator and Planner have tier context when planning implementation.
-
----
-
-## Multi-Model Decision Context
-
-When invoked for a decision analysis, you receive a specific question. You MUST:
-1. **Commit to a recommendation** — do not hedge with "it depends"
-2. **Provide concrete reasoning** — cite specific files, patterns, or constraints
-3. **Acknowledge trade-offs** — show you considered alternatives
-4. **State your confidence level** — high/medium/low with reasoning
-
----
-
-## Invocation Mode Detection
-
-- **Direct** (has AI Kit tools) → Follow the **Information Lookup Order** from code-agent-base
-- **Sub-agent** (prompt has "## Prior AI Kit Context") → Skip AI Kit Recall, use provided context
-
----
-
-## Context Efficiency
-
-- **NEVER use `read_file` to understand code** — use AI Kit compression tools instead
-- **`file_summary`** for structure (exports, imports, call edges — 10x fewer tokens)
-- **`compact`** for specific sections (5-20x token reduction vs read_file)
-- **`digest`** when synthesizing from 3+ sources
-- **`stratum_card`** for files you'll reference repeatedly
-- **`read_file` is ONLY acceptable** when you need exact lines for a pending edit operation
-
-## Parallel Exploration via `lane`
-
-For questions that require trying approach A vs approach B in isolation:
-1. `lane({ action:'create', name:'approach-a' })` — isolated file copies
-2. Apply approach A mentally; record observations
-3. `lane({ action:'create', name:'approach-b' })` — second isolate
-4. Apply approach B mentally; record observations
-5. `lane({ action:'diff', names:['approach-a','approach-b'] })` — compare
-6. Include the diff summary in your output; do NOT merge lanes back (read-only role)
-

package/scaffold/general/agents/templates/adr-template.md

@@ -1,28 +0,0 @@
-# DR-NNN: {Short Title}
-
-**Status:** Proposed | Accepted | Rejected | Deprecated | Superseded
-**Date:** YYYY-MM-DD
-**Participants:** {which Researcher variants participated}
-
-## Context
-{What is the issue? Why are we making this decision?}
-{If superseding, link: "Supersedes DR-NNN."}
-
-## Decision
-{What was decided and why — 2-5 sentences max}
-
-## Decision Analysis Summary
-| Model | Recommendation | Key Reasoning |
-|-------|---------------|---------------|
-
-**Agreements:** {what 3+ models agreed on}
-**Disagreements:** {where they diverged}
-
-## Consequences
-**Positive:** {benefits}
-**Negative:** {trade-offs accepted}
-**Risks:** {what could go wrong, and any mitigations}
-
-## Alternatives Considered
-{Other approaches evaluated and why they were rejected — keeps the "why not" alongside the "why"}
-

package/scaffold/general/agents/templates/execution-state.md

@@ -1,26 +0,0 @@
-# Execution State: {Task Title}
-
-**Status:** PLANNING | IN_PROGRESS | REVIEW | COMPLETED | BLOCKED
-**Started:** {timestamp}
-**Plan:** {link to plan file}
-
-## Phases
-
-| # | Title | Agent | Status | Batch |
-|---|-------|-------|--------|-------|
-
-## Current Batch
-
-**Batch {N}:** {phases in this batch}
-**Status:** IMPLEMENTING | REVIEWING | APPROVED
-
-## Decisions Log
-
-| Decision | Rationale | ADR |
-|----------|-----------|-----|
-
-## Blockers
-
-| Issue | Severity | Assigned |
-|-------|----------|----------|
-

package/scaffold/general/prompts/aikit-ask.prompt.md

@@ -1,13 +0,0 @@
----
-description: "Quick research question — find answer using AI Kit + web search"
-agent: "Researcher-Alpha"
----
-
-## Quick Research
-
-1. **AI Kit Recall** — Search knowledge base for existing answers
-2. **Web Search** — If AI Kit has no relevant results, search the web
-3. **Synthesize** — Combine findings into a clear, concise answer
-4. **Remember** — If the answer is broadly useful, persist it to KB
-
-**Always cite sources** — AI Kit entries, file paths, or URLs.

package/scaffold/general/prompts/aikit-debug.prompt.md

@@ -1,15 +0,0 @@
----
-description: "Systematic error diagnosis: reproduce → trace → diagnose → fix → verify"
-agent: "Debugger"
----
-
-## Debug Workflow
-
-1. **Parse Error** — Use `parse_output` on the error message/stack trace
-2. **AI Kit Recall** — Search for known issues matching this pattern
-3. **Reproduce** — Run the failing command/test to confirm
-4. **Trace** — Use `symbol` and `trace` to follow the call chain
-5. **Diagnose** — Form hypothesis, gather evidence
-6. **Fix** — Implement minimal fix
-7. **Verify** — `check` + `test_run` to confirm fix and no regressions
-8. **Remember** — Persist the fix with category `troubleshooting`

package/scaffold/general/prompts/aikit-design.prompt.md

@@ -1,15 +0,0 @@
----
-description: "Collaborative design session — explore ideas, refine requirements, produce a design spec"
-agent: "Orchestrator"
----
-
-## Design Session
-
-Enter Phase 0 (Design Gate) directly — the user is requesting a design session.
-
-1. **Invoke the brainstorming skill** — interactive design dialogue with user
-2. Follow the skill's full process (auto-selects Simple or Advanced mode)
-3. If Advanced Mode, use Decision Protocol for unresolved technical choices
-4. Terminal state: brainstorming skill invokes writing-plans skill
-
-**🛑 HARD GATE** — Do NOT skip brainstorming. Do NOT write code. Design first.

package/scaffold/general/prompts/aikit-flow-add.prompt.md

@@ -1,84 +0,0 @@
----
-description: "Install a new flow from a git URL or local path — with interactive error recovery"
-agent: "Orchestrator"
----
-
-## Flow Installation Assistant
-
-Install a development flow from a git repository or local directory.
-
-### Usage
-Provide a git URL or local path:
-- `https://github.com/org/my-flow.git`
-- `git@github.com:org/my-flow.git`
-- `./path/to/local/flow`
-- `C:\Users\name\flows\my-flow`
-
-### Workflow
-
-1. **Attempt Install** — Call `flow_add` with the provided source
-2. **On Success** — Show installed flow info with `flow_info`, present summary to user
-3. **On Failure** — Classify the error and enter the appropriate recovery path:
-
-### Error Recovery Paths
-
-#### Git Authentication Failure
-If the error mentions authentication, credentials, 401, 403, permission denied, or SAML:
-
-1. Present the error clearly to the user
-2. Ask which auth method they prefer:
-   - **SSH key**: Walk through `ssh-keygen -t ed25519`, adding the public key to their git host, and retrying with the SSH URL
-   - **Personal Access Token (PAT)**: Guide them to create a PAT in their git host settings, configure `git credential.helper store`, and retry
-   - **Git Credential Manager**: Check if GCM is installed, help install if needed, then retry (GCM opens a browser for auth)
-3. After credentials are configured, retry `flow_add`
-
-#### Network / Connectivity Failure
-If the error mentions timeout, host not found, SSL, or proxy:
-
-1. Present diagnostics: Is VPN needed? Is the URL correct? Is there a proxy?
-2. Guide the user through resolution
-3. Retry after the issue is resolved
-
-#### Format Not Recognized
-If `flow_add` succeeds cloning but returns a format/structure error:
-
-1. Explain that the source was fetched but doesn't match any supported format
-2. List the 3 supported formats:
-   - **Native**: Has a `flow.json` manifest in the root
-   - **Claude Plugin**: Has `.claude-plugin/plugin.json` with skills as steps
-   - **Copilot Agents**: Has `.github/agents/` with agent .md files as steps
-3. Analyze the source structure to understand what's there
-4. Offer to help migrate:
-   - If it has README files or markdown docs → propose creating a `flow.json` that maps them as steps
-   - If it has a different workflow format → propose conversion
-   - If it's missing key parts → guide user to fill them in
-5. Create the missing `flow.json` manifest and step structure
-6. Retry `flow_add` with the fixed source
-
-### Native flow.json Format Reference
-```json
-{
-  "name": "my-flow",
-  "version": "1.0.0",
-  "description": "Description of the flow",
-  "steps": [
-    {
-      "id": "step-id",
-      "name": "Step Name",
-      "instruction": "steps/step-id/README.md",
-      "produces": ["output.md"],
-      "requires": [],
-      "agents": [],
-      "description": "What this step does"
-    }
-  ],
-  "agents": [],
-  "artifacts_dir": ".spec",
-  "install": []
-}
-```
-
-### Post-Install
-After successful installation:
-- Show the flow name, steps, and description via `present`
-- Remind user they can start it with `flow_start`

package/scaffold/general/prompts/aikit-flow-create.prompt.md

@@ -1,80 +0,0 @@
----
-description: "Create a new flow from scratch or migrate an existing workflow to aikit format"
-agent: "Orchestrator"
----
-
-## Flow Creation Assistant
-
-Create a new development flow or migrate an existing workflow to the aikit flow format.
-
-### Mode 1: Create from Scratch
-
-Guide the user through building a complete flow:
-
-1. **Define the workflow** — Ask what the flow should accomplish (e.g., "TDD workflow", "documentation pipeline", "migration process")
-2. **Design steps** — Break the workflow into sequential steps (3-8 is ideal)
-3. **For each step**:
-   - Define the step id, name, and description
-   - Write the instruction (README.md content — what the agent should do)
-   - Identify what it produces (output artifacts)
-   - Identify what it requires (which previous steps must complete first)
-   - Optionally assign preferred agents
-4. **Generate flow.json** — Create the manifest with all steps
-5. **Write step READMEs** — Create instruction files for each step
-6. **Install** — Use `flow_add` to install from the local directory
-
-### Mode 2: Migrate Existing Workflow
-
-If the user has an existing workflow (scripts, docs, runbooks) that they want to convert:
-
-1. **Analyze the source** — Read the existing workflow files to understand the process
-2. **Map to steps** — Identify discrete steps with clear inputs/outputs
-3. **Identify gaps** — What's missing for a complete flow? (instructions? ordering? agents?)
-4. **Fill gaps with user** — Ask user to clarify any ambiguous parts
-5. **Generate the flow** — Create flow.json + step READMEs
-6. **Install and validate** — Use `flow_add` and `flow_info` to verify
-
-### Flow Structure
-
-```
-my-flow/
-  flow.json              — Flow manifest (name, version, steps, agents)
-  steps/
-    step-1/
-      README.md          — Step instructions (what the agent should do)
-    step-2/
-      README.md
-      references/        — Optional reference files for the step
-    ...
-```
-
-### flow.json Format
-```json
-{
-  "name": "my-flow",
-  "version": "1.0.0",
-  "description": "What this flow does",
-  "steps": [
-    {
-      "id": "step-id",
-      "name": "Human-readable Step Name",
-      "instruction": "steps/step-id/README.md",
-      "produces": ["artifact-name.md"],
-      "requires": [],
-      "agents": ["Preferred-Agent"],
-      "description": "Brief description of this step"
-    }
-  ],
-  "agents": [],
-  "artifacts_dir": ".spec",
-  "install": []
-}
-```
-
-### Step README Format
-Each step README should include:
-- **Goal** — What this step accomplishes
-- **Inputs** — What context/artifacts from prior steps are needed
-- **Instructions** — Detailed steps for the agent to follow
-- **Output** — What artifact(s) to produce and where to save them
-- **Acceptance criteria** — How to know the step is complete

package/scaffold/general/prompts/aikit-flow-manage.prompt.md

@@ -1,24 +0,0 @@
----
-description: "List, inspect, update, and remove installed flows"
-agent: "Orchestrator"
----
-
-## Flow Management
-
-Manage your installed development flows.
-
-### Available Actions
-
-1. **List flows** — `flow_list` to see all installed flows with status
-2. **Inspect a flow** — `flow_info` to see detailed steps, agents, and artifacts
-3. **Check status** — `flow_status` to see the active flow and current step
-4. **Update a flow** — `flow_update` to pull latest changes for git-installed flows
-5. **Remove a flow** — `flow_remove` to uninstall (builtin flows cannot be removed)
-6. **Start a flow** — `flow_start` to begin executing a flow
-7. **Reset active flow** — `flow_reset` to clear active flow state
-
-### Workflow
-1. If no specific action requested, start with `flow_list` and present overview
-2. Use `present` to display flow information in a clear table/card format
-3. For updates, warn if there's an active flow that might be affected
-4. For removals, confirm with user before proceeding

package/scaffold/general/prompts/aikit-implement.prompt.md

@@ -1,17 +0,0 @@
----
-description: "Full lifecycle implementation: plan → build → review → commit"
-agent: "Orchestrator"
----
-
-## Implementation Pipeline
-
-Follow the Orchestrator's full workflow:
-
-1. **Phase 0: Design Gate** — Orchestrator checks if design is needed. Creative/additive work triggers brainstorming first. Use `/design` if you want to start with design explicitly.
-2. **Phase 1: Planning** — Research, draft plan, present to user for approval
-3. **Phase 2: Implementation** — Execute phases in parallel batches
-4. **Phase 3: Completion** — Final review, docs, persist learnings
-
-**🛑 MANDATORY STOPS** — After plan, after each batch, after completion.
-
-Refer to the Orchestrator agent's full instructions for the detailed workflow.

package/scaffold/general/prompts/aikit-plan.prompt.md

@@ -1,15 +0,0 @@
----
-description: "Create a detailed TDD implementation plan without executing it"
-agent: "Planner"
----
-
-## Planning Workflow
-
-1. **AI Kit Recall** — Search for past plans, architecture decisions
-2. **FORGE Ground** — Classify tier, scope map, seed unknowns
-3. **Research** — Explore codebase, understand subsystems
-4. **Draft Plan** — 3-10 phases with agent assignments, TDD steps
-5. **Dependency Graph** — Group into parallel batches
-6. **Present** — Show plan with open questions
-
-**🛑 MANDATORY STOP** — Wait for user approval. Do NOT implement.

package/scaffold/general/prompts/aikit-review.prompt.md

@@ -1,24 +0,0 @@
----
-description: "Dual-model code + architecture review pipeline"
-agent: "Orchestrator"
----
-
-## Review Pipeline
-
-### Step 1: Scope
-Identify changed files and their blast radius.
-
-### Step 2: Code Review (parallel)
-Launch Code-Reviewer-Alpha and Code-Reviewer-Beta on the same changeset.
-
-### Step 3: Architecture Review (if needed)
-If changes cross service boundaries or modify interfaces, launch Architect-Reviewer-Alpha and Architect-Reviewer-Beta.
-
-### Step 4: Synthesis
-Merge findings from both reviewers:
-- **Agreements**: Both found same issue → HIGH confidence
-- **Unique findings**: One found, other didn't → verify
-- **Disagreements**: Contradicting verdicts → present both to user
-
-### Step 5: Report
-Present unified review with: verdict, findings by severity, recommended actions.