@vpxa/aikit 0.1.64 → 0.1.66

package/scaffold/general/skills/docs/references/flow-artifacts-guide.md

@@ -0,0 +1,70 @@
+# Flow Artifacts Guide
+
+## What Are Flow Artifacts
+
+Flows produce structured markdown artifacts in `{{artifacts_path}}/`. These files capture requirements, decisions, plan shape, implementation progress, and verification results for the completed flow.
+
+Use artifacts to document the why behind changes. Code diffs still matter, but artifacts usually contain the rationale, constraints, risks, and review findings that should shape durable documentation.
+
+## How to Discover Artifacts
+
+```text
+flow_status()                                      # Get artifactsPath
+find({ pattern: "*.md", path: "<artifactsPath>" }) # Discover artifact files
+digest({ sources: [                                # Compress into working context
+  { path: "<found-artifact-1>" },
+  { path: "<found-artifact-2>" },
+  ...
+]})
+```
+
+Read every artifact `find()` returns. Different flows produce different files — do not assume specific filenames exist.
+
+## Artifact Catalog
+
+| Artifact | Flow | Contains |
+|---|---|---|
+| `design-decisions.md` | `aikit:basic`, `aikit:advanced` | FORGE tier, approach, key decisions, constraints, and risks |
+| `assessment.md` | `aikit:basic` | Goal, affected files, approach steps, risks, and open questions |
+| `spec.md` | `aikit:advanced` | Requirements, acceptance criteria, and scope boundaries |
+| `plan.md` | `aikit:advanced` | Phased implementation plan and architecture decisions |
+| `tasks.md` | `aikit:advanced` | Atomic task list, dependencies, and agent assignments |
+| `progress.md` | `aikit:basic`, `aikit:advanced` | Changes made, tests, deviations, and validation results |
+| `verify-report.md` | `aikit:basic`, `aikit:advanced` | Verdict, quality gates, review findings, security, and recommendation |
+
+## Artifact-to-Documentation Mapping
+
+| Artifact | Contains | Documentation Target | Action |
+|---|---|---|---|
+| `design-decisions.md` | FORGE tier, approach, key decisions | `docs/decisions/` | Create or update ADRs via `adr-skill` for each key decision |
+| `design-decisions.md` | Architecture approach, constraints | `docs/architecture/overview.md` | Update the design rationale section |
+| `spec.md` | Requirements, acceptance criteria | `docs/reference/` | Update API or component reference when public surface changed |
+| `plan.md` | Architecture decisions, phase design | `docs/architecture/` | Update architecture docs with structural changes |
+| `tasks.md` | Task breakdown, dependencies | Usually skip | Only document if it reveals new component boundaries |
+| `progress.md` | Files changed, deviations, tests | `docs/guides/testing.md` | Update when testing strategy changed |
+| `progress.md` | Deviations from plan | `docs/decisions/` | Document significant deviations as ADRs |
+| `verify-report.md` | Code review findings, security | `docs/architecture/overview.md` | Update if findings reveal architectural patterns |
+| `verify-report.md` | Security concerns | `docs/guides/` | Create or update security guidance when concerns are material |
+
+## Reading Strategy
+
+Read every artifact `find()` returns. Triage by content type:
+
+| Content Signal | Documentation Value | Action |
+|---|---|---|
+| Decisions, rationale, constraints | High — durable knowledge | Extract into `docs/decisions/` or architecture docs |
+| Requirements, scope, acceptance criteria | High — defines intent | Update reference docs if public surface changed |
+| Review findings, security concerns, quality gates | Medium — surfaces issues | Update architecture or guides if findings are material |
+| Implementation progress, task lists | Low — transient | Document only meaningful deviations from the plan |
+
+Skip artifacts that only repeat completed work with no insights beyond the code diff.
+
+> The catalog and mapping tables above list artifacts from built-in flows (`aikit:basic`, `aikit:advanced`). Custom flows may produce entirely different artifacts — always discover dynamically with `find()` and classify by content, not by filename.
+
+## What Not to Document
+
+| Avoid | Do Instead |
+|---|---|
+| Copying artifact text verbatim into `docs/` | Extract decisions, rationale, constraints, and stable guidance |
+| Documenting every task or progress update | Keep only durable insights that help future readers |
+| Mirroring temporary planning details | Preserve the final reasoning, not the transient workflow chatter |

package/scaffold/general/skills/docs/references/project-knowledge-gotchas.md

@@ -0,0 +1,32 @@
+# Project Knowledge — Gotchas
+
+Common pitfalls when documenting project knowledge. Reference this during Phase 2 (Investigate) and Phase 4 (Validate).
+
+## Environment Gotchas
+
+**Monorepos:** Root `package.json` may have no source — check for `workspaces`, `packages/`, or `apps/` directories. Each workspace may have independent dependencies and conventions. Map each sub-package separately.
+
+**Outdated README:** README often describes intended architecture, not the current one. Cross-reference with actual file structure before treating any README claim as fact.
+
+**TypeScript path aliases:** `tsconfig.json` `paths` config means imports like `@/foo` don't map directly to the filesystem. Map aliases to real paths before documenting structure.
+
+**Generated/compiled output:** Never document patterns from `dist/`, `build/`, `generated/`, `.next/`, `out/`, or `__pycache__/`. These are artefacts — document source conventions only.
+
+**`.env.example` reveals required config:** Secrets are never committed. Read `.env.example`, `.env.template`, or `.env.sample` to discover required environment variables.
+
+**`devDependencies` ≠ production stack:** Only `dependencies` (or equivalent) runs in production. Document linters, formatters, and test frameworks separately as dev tooling in `stack.md`.
+
+**Test TODOs ≠ production debt:** TODOs inside test directories are coverage gaps, not production technical debt. Separate them in `concerns.md`.
+
+**High-churn files = fragile areas:** Files appearing most in recent `git_context({})` output have the highest modification rate and likely hidden complexity. Always note them in `concerns.md`.
+
+## Anti-Pattern Table
+
+| ❌ Don't | ✅ Do instead |
+|---------|--------------|
+| "Uses Clean Architecture with Domain/Data layers" (when no such directories exist) | State only what directory structure actually shows |
+| "This is a Next.js project" (without checking `package.json`) | Check `dependencies` first. State what's actually there |
+| Guess the database from a variable name like `dbUrl` | Check manifest for `pg`, `mysql2`, `mongoose`, `prisma`, etc. |
+| Document `dist/` or `build/` naming patterns as conventions | Source files only |
+| Assume README describes current architecture | Cross-reference with actual file structure via `analyze_structure` |
+| Treat test TODOs as production tech debt | Separate coverage gaps from production concerns in `concerns.md` |

package/scaffold/general/skills/docs/references/project-knowledge-templates.md

@@ -0,0 +1,281 @@
+# Project Knowledge Templates
+
+Templates for the seven project knowledge documents in `docs/architecture/`. Use these to ensure consistent structure across projects.
+
+## stack.md
+
+```markdown
+# Stack
+
+## Language and Runtime
+
+| Item | Version | Notes |
+|------|---------|-------|
+| {language} | {version} | {notes} |
+
+## Frameworks
+
+| Framework | Version | Role |
+|-----------|---------|------|
+| {name} | {version} | {role} |
+
+## Production Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| {name} | {version} | {purpose} |
+
+## Dev Tooling
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| {name} | {version} | {purpose} |
+
+## Evidence
+
+- `package.json` / `requirements.txt` / `go.mod` — dependency versions
+- `tsconfig.json` / `pyproject.toml` — language configuration
+```
+
+## structure.md
+
+```markdown
+# Structure
+
+## Directory Layout
+
+```
+{root}/
+├── {dir}/    ← {purpose}
+│   └── ...
+└── {dir}/    ← {purpose}
+```
+
+## Entry Points
+
+| Entry Point | Path | Type |
+|-------------|------|------|
+| {name} | `{path}` | CLI / HTTP / Library |
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `{path}` | {purpose} |
+
+## Packages (monorepo only)
+
+| Package | Path | Purpose |
+|---------|------|---------|
+| {name} | `{path}` | {purpose} |
+
+## Evidence
+
+- `analyze_structure` output — directory tree
+- `analyze_entry_points` output — entry points
+```
+
+## design.md
+
+```markdown
+# Design
+
+## Architectural Pattern
+
+{Pattern name} — {one-sentence description of how it applies here}.
+
+## Layers
+
+| Layer | Directory | Responsibility |
+|-------|-----------|----------------|
+| {name} | `{path}` | {responsibility} |
+
+## Data Flow
+
+```
+{source} → {transform} → {destination}
+```
+
+{Brief description of primary data paths.}
+
+## Component Boundaries
+
+| Component | Owns | Depends On |
+|-----------|------|------------|
+| {name} | {responsibility} | {dependencies} |
+
+## Key Patterns
+
+| Pattern | Where Used | Purpose |
+|---------|-----------|---------|
+| {name} | `{path}` | {purpose} |
+
+## Evidence
+
+- `analyze_structure` output — layers
+- `analyze_patterns` output — design patterns
+- `analyze_diagram` output — component diagrams
+```
+
+## conventions.md
+
+```markdown
+# Conventions
+
+## Naming
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Files | {convention} | `{example}` |
+| Functions | {convention} | `{example}` |
+| Types/Interfaces | {convention} | `{example}` |
+| Constants | {convention} | `{example}` |
+
+## Formatting
+
+- Formatter: {tool} with {config file}
+- Linter: {tool} with {config file}
+- Line length: {limit}
+- Indentation: {style}
+
+## Error Handling
+
+{Describe the project's error handling pattern: throw/catch, Result type, error codes, etc.}
+
+## Import Conventions
+
+| Import Type | Convention | Example |
+|-------------|-----------|---------|
+| Internal | {pattern} | `{example}` |
+| External | {pattern} | `{example}` |
+| Type-only | {pattern} | `{example}` |
+
+## Evidence
+
+- `analyze_patterns` output — detected conventions
+- Linter/formatter config files — enforced rules
+```
+
+## integrations.md
+
+```markdown
+# Integrations
+
+## External APIs
+
+| Service | Protocol | Auth | Config |
+|---------|----------|------|--------|
+| {name} | REST / gRPC / GraphQL | {auth method} | `{env var or config}` |
+
+## Databases
+
+| Database | Driver | Connection | Usage |
+|----------|--------|------------|-------|
+| {name} | {driver package} | `{env var}` | {what it stores} |
+
+## Authentication
+
+{Describe auth mechanism: JWT, OAuth, API keys, sessions, etc.}
+
+## Monitoring and Observability
+
+| Tool | Purpose | Config |
+|------|---------|--------|
+| {name} | Logging / Metrics / Tracing | `{config}` |
+
+## CI/CD
+
+| Platform | Config | Stages |
+|----------|--------|--------|
+| {name} | `{config file}` | {stages} |
+
+## Evidence
+
+- `analyze_dependencies` output — external packages
+- `.env.example` — required environment variables
+- CI config files — pipeline definitions
+```
+
+## testing.md
+
+```markdown
+# Testing
+
+## Framework
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| {name} | {version} | Unit / Integration / E2E |
+
+## File Organization
+
+| Pattern | Location | Example |
+|---------|----------|---------|
+| {convention} | `{path}` | `{example file}` |
+
+## Mocking Strategy
+
+{Describe how mocks are created and used: manual, library, DI, etc.}
+
+## Coverage
+
+- Target: {percentage or policy}
+- Tool: {coverage tool}
+- Config: `{config file}`
+
+## Running Tests
+
+```bash
+{command to run all tests}
+{command to run specific tests}
+{command to run with coverage}
+```
+
+## Evidence
+
+- `analyze_patterns` output — test patterns
+- `test_run({})` output — test health
+- Test config files — framework configuration
+```
+
+## concerns.md
+
+```markdown
+# Concerns
+
+## Tech Debt
+
+| Area | Description | Severity | Evidence |
+|------|-------------|----------|----------|
+| {area} | {description} | High / Medium / Low | `{file or tool}` |
+
+## Known Issues
+
+| Issue | Impact | Workaround |
+|-------|--------|------------|
+| {issue} | {impact} | {workaround or "None"} |
+
+## Security Risks
+
+| Risk | Severity | Mitigation |
+|------|----------|------------|
+| {risk} | {severity} | {mitigation} |
+
+## Performance Bottlenecks
+
+| Area | Symptom | Evidence |
+|------|---------|----------|
+| {area} | {symptom} | `{file or metric}` |
+
+## High-Churn Files
+
+| File | Recent Changes | Why |
+|------|---------------|-----|
+| `{path}` | {change count} | {reason} |
+
+## Evidence
+
+- `audit()` output — health issues
+- `dead_symbols({})` output — dead code
+- `git_context({})` output — high-churn files
+```

package/scaffold/general/skills/docs/references/project-knowledge-workflow.md

@@ -0,0 +1,80 @@
+# Project Knowledge — Workflow
+
+Detailed workflow for acquiring and documenting project knowledge into `docs/architecture/`.
+
+## Four-Phase Workflow
+
+```
+- [ ] Phase 1: Scan with AI Kit tools, read intent documents
+- [ ] Phase 2: Investigate each documentation area
+- [ ] Phase 3: Populate all seven docs in docs/architecture/
+- [ ] Phase 4: Validate docs, present findings, resolve all [ASK USER] items
+```
+
+### Phase 1: Scan and Read Intent
+
+```
+onboard({ path: "." })                           # Full codebase scan
+produce_knowledge({ path: "." })                  # Comprehensive analysis
+analyze_structure({ path: "." })                  # Project layout, packages, layers
+analyze_dependencies({ path: "." })               # All dependencies + import graph
+```
+
+Then read `README`, `PRD`, `TRD`, `ROADMAP`, `SPEC`, `DESIGN` files if they exist.
+Summarise the stated project intent before reading any source code.
+
+### Phase 2: Investigate
+
+Use Phase 1 tool outputs to answer questions for each of the seven documents. Run additional targeted tools:
+
+| Document | Investigation Tools |
+|----------|-------------------|
+| stack.md | `analyze_dependencies` → manifests, frameworks; `analyze_structure` → runtime signals |
+| structure.md | `analyze_structure` → file tree, packages; `analyze_entry_points` → entry points, key files |
+| design.md | `analyze_structure` → layers; `analyze_patterns` → design patterns; `analyze_diagram` → component diagrams |
+| conventions.md | `analyze_patterns` → naming, formatting; `search("conventions")` → detected conventions |
+| integrations.md | `analyze_dependencies` → external deps; `search("API\|database\|auth\|webhook")` → integration points |
+| testing.md | `analyze_patterns` → test patterns; `search("test framework")` → test setup; `test_run({})` → test health |
+| concerns.md | `audit({ path: "." })` → health issues; `dead_symbols({})` → dead code; `git_context({})` → high-churn files |
+
+### Phase 3: Populate Documents
+
+Create each document in `docs/architecture/` in this order:
+
+1. **stack.md** — Language, runtime version, frameworks, production dependencies, dev tooling
+2. **structure.md** — Directory layout, entry points, key files, package organization
+3. **design.md** — Layers, architectural patterns, data flow, component boundaries
+4. **conventions.md** — Naming conventions, formatting rules, error handling patterns, import conventions
+5. **integrations.md** — External APIs, databases, auth providers, monitoring, CI/CD
+6. **testing.md** — Test frameworks, file organization, mocking strategy, coverage approach
+7. **concerns.md** — Tech debt, known bugs, security risks, performance bottlenecks, high-churn files
+
+Rules:
+- Use `[TODO]` for anything that cannot be determined from code
+- Use `[ASK USER]` where the right answer requires team intent
+- Include an "Evidence" section in each doc with file paths and tool receipts
+
+### Phase 4: Validate, Repair, Verify
+
+Run this mandatory validation loop before finalizing:
+
+1. For each non-trivial claim, confirm at least one evidence reference exists
+2. If any required section is missing or unsupported → fix and re-validate
+3. Repeat until all seven docs pass
+
+Validation pass criteria:
+- No unsupported claims
+- No empty required sections
+- Unknowns use `[TODO]` rather than assumptions
+- Team-intent gaps are explicitly marked `[ASK USER]`
+
+Then present a summary, list every `[ASK USER]` item as a numbered question, and highlight any Intent vs. Reality divergences from Phase 1.
+
+## Focus Area Mode
+
+If the user specifies a focus area (e.g., "architecture only" or "testing and concerns"):
+
+1. Always run Phase 1 in full
+2. Fully complete focus-area documents first
+3. For non-focus documents, keep required sections present and mark unknowns as `[TODO]`
+4. Still run the Phase 4 validation loop on all seven documents

package/packages/cli/dist/constants-D3v4VDf0.js

@@ -1 +0,0 @@
-const e=`aikit`,t={type:`stdio`,command:`npx`,args:[`-y`,`@vpxa/aikit`,`serve`]},n=[`aikit`,`brainstorming`,`multi-agents-development`,`session-handoff`,`requirements-clarity`,`lesson-learned`,`c4-architecture`,`adr-skill`,`present`,`frontend-design`,`react`,`typescript`],r=[`aikit-basic`,`aikit-advanced`],i={"chat.agentFilesLocations":{"~/.claude/agents":!1},"github.copilot.chat.copilotMemory.enabled":!0,"chat.customAgentInSubagent.enabled":!0,"chat.useNestedAgentsMdFiles":!0,"chat.useAgentSkills":!0,"github.copilot.chat.switchAgent.enabled":!0,"workbench.browser.enableChatTools":!0,"chat.mcp.apps.enabled":!0,"chat.instructionsFilesLocations":{"~/.copilot/instructions":!0,".github/instructions":!0}};export{i as a,n as i,t as n,e as r,r as t};