@vpxa/aikit 0.1.65 → 0.1.66

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

@@ -1,281 +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
+# 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
 ```