@vpxa/aikit 0.1.128 → 0.1.129

package/scaffold/dist/adapters/skills.mjs

@@ -1 +1 @@
-import{SKILLS as e}from"../definitions/skills/index.mjs";function t(){let t=[];for(let[n,r]of Object.entries(e))for(let{file:e,content:i}of r)t.push({path:`${n}/${e}`,content:i});return t}export{t as generateSkills};
+import{SKILLS as e}from"../definitions/skills/index.mjs";import{ALL_BLOCK_DOCS as t,BLOCK_DOCS_BY_SKILL as n,BLOCK_TYPE_LIST as r}from"../generated/block-docs.mjs";const i={bySkill:n,all:t,typeList:r};function a(){let t=[];for(let[n,r]of Object.entries(e)){let e=typeof r==`function`?r({blockDocs:i}):r;for(let{file:r,content:i}of e)t.push({path:`${n}/${r}`,content:i})}return t}export{a as generateSkills};

package/scaffold/dist/definitions/prompts.mjs

@@ -222,4 +222,129 @@ Each step README should include:
 - **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`}};export{e as PROMPTS};
+- **Acceptance criteria** — How to know the step is complete`},docs:{description:`Deep codebase understanding — analyze, learn, document, and visualize the entire project as an interactive knowledge graph`,agent:`Orchestrator`,tools:[`onboard`,`analyze`,`audit`,`produce_knowledge`,`graph`,`measure`,`blast_radius`,`search`,`symbol`,`trace`,`dead_symbols`,`file_summary`,`compact`,`digest`,`knowledge`,`present`,`check`,`test_run`,`git_context`],content:`## Understand & Document — Full Codebase Intelligence
+
+Turn this codebase into a deeply understood, richly documented, and visually explorable project.
+"Understand Anything" philosophy: **graphs that teach > graphs that impress.**
+
+This is NOT just documentation generation — it is a full **analyze → understand → learn → document → present** pipeline.
+
+### Phase 1: Deep Scan (parallel analysis)
+
+Run all analysis tools in parallel to build a comprehensive baseline:
+
+1. **Onboard** — \`onboard({ path: "." })\` if not already done (check \`status()\` first)
+2. **Structure** — \`analyze({ aspect: "structure", path: "." })\`
+3. **Dependencies** — \`analyze({ aspect: "dependencies", path: "." })\`
+4. **Symbols** — \`analyze({ aspect: "symbols", path: "." })\`
+5. **Patterns** — \`analyze({ aspect: "patterns", path: "." })\`
+6. **Entry Points** — \`analyze({ aspect: "entry_points", path: "." })\`
+7. **Diagrams** — \`analyze({ aspect: "diagram", path: "." })\`
+8. **Health Audit** — \`audit({ path: "." })\`
+9. **Complexity** — \`measure({ path: "." })\`
+10. **Git Context** — \`git_context({ include_diff: true })\`
+11. **Dead Symbols** — \`dead_symbols({ path: "." })\`
+
+Stash all results for later phases.
+
+### Phase 2: Knowledge Graph Construction
+
+Build a navigable knowledge graph of the codebase:
+
+1. **Discover modules** — \`graph({ action: 'find_nodes' })\` to get all indexed modules
+2. **Map relationships** — For key modules, \`graph({ action: 'neighbors', node_id, direction: 'both' })\`
+3. **Trace critical paths** — Use \`trace({ start: "<entry-point>", direction: "forward" })\` on each entry point
+4. **Identify layers** — Classify modules into architectural layers (API, Service, Domain, Data, Infrastructure, UI, Utility, Config)
+5. **Detect communities** — \`graph({ action: 'detect_communities' })\` to find natural module clusters
+6. **Symbol deep-dive** — For each public API/export, \`symbol({ name })\` to understand usage
+
+Persist the graph structure and layer classification.
+
+### Phase 3: Multi-Agent Understanding (parallel dispatch)
+
+Dispatch Researcher agents **in parallel** to deeply understand different aspects:
+
+**Researcher-Alpha** — Architecture & Design Patterns:
+- What architectural style is used? (layered, hexagonal, microservice, monolith)
+- What design patterns appear? (repository, factory, strategy, observer, etc.)
+- How is data flow organized? (request lifecycle, event pipeline, etc.)
+
+**Researcher-Beta** — Business Logic & Domain:
+- What are the core business domains/bounded contexts?
+- What are the key business flows and processes?
+- What domain entities and value objects exist?
+- How is business logic separated from infrastructure?
+
+**Researcher-Gamma** — Integration & Infrastructure:
+- What external services, APIs, databases are used?
+- How is authentication/authorization handled?
+- What is the deployment topology?
+- What monitoring, logging, observability exists?
+
+**Researcher-Delta** — Quality & Concerns:
+- What is the test coverage strategy?
+- What tech debt or code smells exist?
+- What security concerns should be noted?
+- What performance bottlenecks are visible?
+- What are the highest-complexity files?
+
+### Phase 4: Document Everything
+
+Load the \`docs\` skill and generate comprehensive documentation:
+
+1. **Project Knowledge** (7 architecture docs):
+   - \`docs/architecture/stack.md\` — Language, runtime, frameworks, all dependencies
+   - \`docs/architecture/structure.md\` — Directory layout, entry points, key files
+   - \`docs/architecture/design.md\` — Layers, patterns, data flow, component boundaries
+   - \`docs/architecture/conventions.md\` — Naming, formatting, error handling, imports
+   - \`docs/architecture/integrations.md\` — External APIs, databases, auth, monitoring
+   - \`docs/architecture/testing.md\` — Test frameworks, file organization, mocking
+   - \`docs/architecture/concerns.md\` — Tech debt, security risks, performance issues
+
+2. **Component Docs** — For each major module/component:
+   - \`docs/architecture/components/{name}.md\` — Purpose, API, design decisions, data flow
+
+3. **Reference Docs**:
+   - \`docs/reference/api.md\` — API surface, endpoints, schemas
+   - \`docs/reference/configuration.md\` — Config options, environment variables
+
+4. **Guides**:
+   - \`docs/guides/onboarding.md\` — Guided tour for new developers (dependency-ordered walkthrough)
+   - \`docs/guides/architecture-tour.md\` — Visual architecture walkthrough
+
+5. **Project Overview**:
+   - \`docs/README.md\` — Index linking all docs, project summary
+
+6. **Persist Knowledge** — \`produce_knowledge({ path: "." })\` + \`knowledge({ action: "remember", ... })\` for key findings
+
+### Phase 5: Interactive Presentation
+
+Present the understanding as a rich interactive dashboard using \`present\`:
+
+1. **Architecture Overview** — Mermaid diagram of system layers and component relationships
+2. **Dependency Graph** — Module dependency visualization
+3. **Metrics Dashboard** — File count, complexity distribution, test coverage, health score
+4. **Knowledge Map** — Key modules with descriptions, organized by architectural layer
+5. **Guided Tour** — Recommended reading order for codebase onboarding
+6. **Concerns Board** — Tech debt, dead code, security risks as a status board
+7. **Business Domain Map** — Domain entities and their relationships
+
+Use the \`c4-architecture\` skill for generating proper C4 architecture diagrams (Context, Container, Component levels).
+
+### Output Summary
+
+After all phases complete, present a final summary to the user:
+- Total files analyzed, modules discovered, patterns detected
+- Architecture style and key design decisions identified
+- Number of docs generated and their locations
+- Top concerns and recommendations
+- Links to the interactive dashboard
+
+### Rules
+
+- **Every claim must be traceable** to source files or tool output
+- **Never infer or assume** — only document what is verifiable
+- **Mark unknowns** with \`[TODO]\` and intent-dependent decisions with \`[ASK USER]\`
+- **Delegate to specialists**: architecture diagrams → \`c4-architecture\` skill, ADRs → \`adr-skill\`
+- **Compress between phases** — use \`digest\` and \`stash\` to manage context
+- **🛑 STOP after Phase 5** — present results and ask user for feedback before any follow-up work`}};export{e as PROMPTS};