@vpxa/aikit 0.1.63 → 0.1.65

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};