baldart 3.6.2

package/framework/agents/github-issue-subagent.md

@@ -0,0 +1,252 @@
+# GitHub Issue Workflow
+
+## Purpose
+
+Define how to create, update, and manage GitHub issues.
+
+## Scope
+
+**In**: Issue creation, labeling, status tracking, resolution workflow.
+**Out**: Project management (see agents/workflows.md).
+
+## Do
+
+- Create issues for bugs, features, and tasks
+- Use clear, descriptive titles
+- Add appropriate labels
+- Link to related PRs/issues
+- Update status regularly
+
+## Do Not
+
+- Close issues prematurely
+- Skip reproduction steps for bugs
+- Use vague titles
+
+## Issue Types
+
+### Bug Report
+
+**Title format**: `[BUG] Brief description of the issue`
+
+**Template**:
+
+```markdown
+## Description
+[Clear description of the bug]
+
+## Steps to Reproduce
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Expected Behavior
+[What should happen]
+
+## Actual Behavior
+[What actually happens]
+
+## Environment
+- OS: [e.g., macOS 13.0]
+- Browser: [e.g., Chrome 120]
+- Version: [e.g., 1.2.3]
+
+## Screenshots/Logs
+[If applicable]
+
+## Additional Context
+[Any other relevant information]
+```
+
+### Feature Request
+
+**Title format**: `[FEATURE] Brief description of the feature`
+
+**Template**:
+
+```markdown
+## Problem Statement
+[What problem does this solve?]
+
+## Proposed Solution
+[How should it work?]
+
+## Alternatives Considered
+[Other approaches considered]
+
+## Additional Context
+[Any other relevant information]
+```
+
+### Task
+
+**Title format**: `[TASK] Brief description of the task`
+
+**Template**:
+
+```markdown
+## Description
+[What needs to be done?]
+
+## Acceptance Criteria
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] [Criterion 3]
+
+## Related Issues/PRs
+[Links to related items]
+```
+
+## Labels
+
+### Type Labels
+
+- `bug`: Something isn't working
+- `feature`: New feature request
+- `enhancement`: Improvement to existing feature
+- `documentation`: Documentation updates
+- `refactor`: Code refactoring
+- `test`: Test-related changes
+
+### Priority Labels
+
+- `priority: critical`: Requires immediate attention
+- `priority: high`: Important, address soon
+- `priority: medium`: Normal priority
+- `priority: low`: Nice to have
+
+### Status Labels
+
+- `status: todo`: Not started
+- `status: in-progress`: Being worked on
+- `status: blocked`: Blocked by another issue
+- `status: review`: Ready for review
+- `status: done`: Completed
+
+### Area Labels
+
+- `area: frontend`: Frontend code
+- `area: backend`: Backend code
+- `area: api`: API changes
+- `area: database`: Database changes
+- `area: devops`: DevOps/infrastructure
+
+### Special Labels
+
+- `good first issue`: Good for newcomers
+- `help wanted`: Looking for contributors
+- `vibe review`: Fixed, needs user verification
+- `qa`: QA/testing issue
+- `wontfix`: Will not be fixed
+- `duplicate`: Duplicate of another issue
+
+## Issue Workflow
+
+### 1. Creation
+
+- Use appropriate template
+- Fill in all sections
+- Add relevant labels
+- Assign if known
+
+### 2. Triage
+
+- Review new issues
+- Add/update labels
+- Set priority
+- Assign to milestone if applicable
+
+### 3. Development
+
+- Link issue in commit: `Fixes #123`
+- Link issue in PR description
+- Update issue with progress
+- Add `status: in-progress` label
+
+### 4. Review
+
+- Reference issue in PR
+- Wait for CI/CD checks
+- Get approval
+- Merge PR
+
+### 5. Verification
+
+- Add `vibe review` label
+- Leave issue open
+- User/QA verifies fix
+- Add verification comment
+- Only close after verification
+
+## Issue Resolution
+
+### For Bug Fixes
+
+1. Implement fix
+2. Add tests
+3. Create PR referencing issue
+4. Merge PR
+5. Add `vibe review` label
+6. Leave issue open
+7. Verify in production
+8. Add verification comment
+9. Leave open for tracking
+
+### For Features
+
+1. Implement feature
+2. Add tests and docs
+3. Create PR referencing issue
+4. Merge PR
+5. Deploy to production
+6. Update issue with deployment info
+7. Can close after successful deployment
+
+## Linking Issues and PRs
+
+### In Commit Messages
+
+```bash
+git commit -m "Fix login bug
+
+Fixes #123
+Closes #456"
+```
+
+### In PR Descriptions
+
+```markdown
+## Description
+[PR description]
+
+## Related Issues
+Fixes #123
+Relates to #456
+Blocks #789
+```
+
+## Issue Search
+
+Use GitHub search to find issues:
+
+- `is:open is:issue label:bug` - Open bugs
+- `is:closed is:issue label:feature` - Closed features
+- `is:issue author:@me` - Your issues
+- `is:issue assignee:@me` - Assigned to you
+
+## Issue Templates
+
+Create `.github/ISSUE_TEMPLATE/` directory with:
+
+- `bug_report.md`
+- `feature_request.md`
+- `task.md`
+
+## Automation
+
+Consider GitHub Actions for:
+
+- Auto-labeling based on title
+- Stale issue management
+- PR/issue linking validation
+- Automatic milestone assignment

package/framework/agents/index.md

@@ -0,0 +1,261 @@
+<!-- contamination-scan: skip
+     This routing manifest uses literal example module names ("users.md",
+     "customer.md", etc.) in illustrative API/UI documentation flows. They
+     are pedagogical examples, not project-leak. -->
+# Agents Index
+
+## Purpose
+
+Route agents to the right module with minimal reading.
+
+## Routing Rules
+
+### Documentation Routing
+
+- **MANDATORY pre-read for any skill/agent that touches project-specific paths, identity, stack, or feature toggles** -> read `agents/project-context.md`. Skills consult `baldart.config.yml` + `.baldart/overlays/<skill>.md` instead of hard-coded paths; missing keys MUST be asked, never assumed.
+- If needing to understand codebase structure, existing patterns, or architecture before planning -> MUST invoke `codebase-architect` agent (via Task tool) first; do not proceed without architectural understanding.
+- If touching API endpoints or request/response shape -> read `agents/api-contracts.md` and `${paths.references_dir}/api/index.md` (then specific API module for your domain).
+- If touching database schema or fields -> read `agents/data-model.md` and `${paths.references_dir}/data-model.md`.
+- If touching UI pages/routes or flows -> read `${paths.references_dir}/ui/index.md` (then specific UI module for your domain).
+- If touching design-review workflows or UI guidelines -> read `agents/design-review.md` and project-specific UI guidelines.
+- If touching architecture, auth, or tech stack -> read `agents/architecture.md`.
+- If touching workflow/process/commits/backlog -> read `agents/workflows.md`.
+- If touching testing or QA issues -> read `agents/testing.md`.
+- If touching GitHub issues or issue workflow -> read `agents/github-issue-subagent.md`.
+- If touching terminology or naming -> read `agents/coding-standards.md`.
+- If touching env vars or scripts -> read `agents/runbook.md` and `agents/env-reference.md`.
+- If touching operational procedures (backup, cleanup, secrets) -> read `docs/operations/` if it exists in your project.
+- If touching security or auth risk -> read `agents/security.md`.
+- If touching performance limits or scaling -> read `agents/performance.md`.
+- If touching monitoring/logging -> read `agents/observability.md`.
+- If building or maintaining a derived LLM wiki overlay (`${paths.wiki_dir}/`) -> read `agents/llm-wiki-methodology.md` and invoke `wiki-curator` / `/capture`.
+- For day-to-day status -> read and update `${paths.references_dir}/project-status.md`.
+- For legacy context -> read `archive/project_full_legacy.md` if it exists.
+
+### Agent Invocation Routing (via Task tool)
+
+**Single source of truth**: See [`.claude/agents/REGISTRY.md`](../.claude/agents/REGISTRY.md) for the full agent map, decision tree, capabilities, and tool access.
+
+When adding or updating agents, update REGISTRY.md — not this file.
+
+## Modules
+
+- `agents/architecture.md`
+- `agents/coding-standards.md`
+- `agents/workflows.md`
+- `agents/testing.md`
+- `agents/security.md`
+- `agents/performance.md`
+- `agents/observability.md`
+- `agents/api-contracts.md`
+- `agents/data-model.md`
+- `agents/runbook.md`
+- `agents/env-reference.md`
+- `agents/maintenance-protocol.md`
+- `agents/github-issue-subagent.md`
+- `agents/design-review.md`
+- `agents/skills-mapping.md`
+- `agents/llm-wiki-methodology.md` — LLM wiki overlay methodology + auto-learning loop (since v2.0.0)
+- `agents/project-context.md` — Project context protocol: `baldart.config.yml` + overlays + missing-key handling (since v3.0.0)
+
+## Where to Document (Decision Tree)
+
+Use these flowcharts to determine where documentation changes belong.
+
+### Code Change Documentation
+
+When you make a code change, follow this decision tree:
+
+```
+START: You made a code change
+  |
+  v
+Is it an API endpoint change?
+  |-- YES --> Update ${paths.references_dir}/api/{module}.md
+  |            (Organize API docs by domain/feature)
+  |
+  v
+Is it a database schema change?
+  |-- YES --> Update ${paths.references_dir}/data-model.md
+  |            + Create ADR if structural
+  |
+  v
+Is it a UI page/route change?
+  |-- YES --> Update ${paths.references_dir}/ui/{domain}.md (see ui/index.md)
+  |
+  v
+Is it an architectural decision?
+  |-- YES --> Create ADR in ${paths.adrs_dir}/
+  |            + Update agents/architecture.md if persistent
+  |
+  v
+Is it a security-related change?
+  |-- YES --> Update agents/security.md
+  |            + Create ADR if policy change
+  |
+  v
+Is it a workflow/process change?
+  |-- YES --> Update agents/workflows.md
+  |
+  v
+Does it affect project status?
+  |-- YES --> Update ${paths.references_dir}/project-status.md
+  |
+  v
+DONE: Commit with docs updated
+```
+
+### API Module Routing
+
+When documenting an API endpoint, select the correct module based on your project's domain structure:
+
+```
+START: New or modified API endpoint
+  |
+  v
+Identify the domain/feature area
+  |
+  v
+Does a module exist for this domain?
+  |-- YES --> Update that module (e.g., auth.md, users.md, products.md)
+  |-- NO --> Create new module or add to closest existing module
+  |
+  v
+Update ${paths.references_dir}/api/index.md with module reference
+  |
+  v
+DONE: Document endpoint following project standards
+```
+
+### Documentation-Only Changes
+
+When you need to update documentation without code changes:
+
+```
+START: Documentation update needed
+  |
+  v
+Is it fixing a typo/broken link?
+  |-- YES --> Fix directly, no ADR needed
+  |
+  v
+Is it clarifying existing behavior?
+  |-- YES --> Update the relevant reference doc
+  |            (data-model, ui/{domain}, api/*)
+  |
+  v
+Is it adding new guidance/rules?
+  |-- YES --> Is it agent-specific?
+  |            |-- YES --> Update agents/{topic}.md
+  |            |-- NO --> Update ${paths.references_dir}/{topic}.md
+  |
+  v
+Is it documenting a decision?
+  |-- YES --> Create ADR in ${paths.adrs_dir}/
+  |
+  v
+Is it changing this file (index.md)?
+  |-- YES --> Update this file + AGENTS.md routing section
+  |
+  v
+DONE: Commit with clear message
+```
+
+---
+
+## Quick Reference Table
+
+| What Changed | Where to Document | Also Update |
+|--------------|-------------------|-------------|
+| API endpoint | `${paths.references_dir}/api/{domain}.md` | `api/index.md` if new endpoint |
+| Database schema | `${paths.references_dir}/data-model.md` | API module if affects endpoints |
+| UI page/route | `${paths.references_dir}/ui/{domain}.md` | `ui/index.md` if new page |
+| Architecture decision | `${paths.adrs_dir}/ADR-*.md` | `agents/architecture.md` |
+| Workflow/process | `agents/workflows.md` | `AGENTS.md` if MUST rule |
+| Security policy | `agents/security.md` | ADR if major change |
+| Testing approach | `agents/testing.md` | - |
+| Environment setup | `agents/runbook.md` | - |
+| Project status | `${paths.references_dir}/project-status.md` | - |
+
+---
+
+## Realistic Examples
+
+### Example 1: Adding a new API endpoint
+
+You add `POST /api/v1/users/favorites`:
+
+1. Determine module: User-related --> `users.md` or `customer.md`
+2. Add endpoint documentation following the standard format
+3. Update `api/index.md` endpoint count if needed
+4. Update `data-model.md` if new database fields
+5. Commit: `[FEAT-XXX] Add favorites endpoint with docs`
+
+### Example 2: Changing database schema
+
+You add a `lastLoginAt` field to the `users` table/collection:
+
+1. Update `${paths.references_dir}/data-model.md` with new field
+2. Check if any API endpoints need doc updates
+3. No ADR needed (field addition is non-breaking)
+4. Commit: `[FEAT-XXX] Add lastLoginAt field to users`
+
+### Example 3: Architectural decision
+
+You decide to use Redis for caching:
+
+1. Create `${paths.adrs_dir}/ADR-20260123-redis-caching.md`
+2. Update `agents/architecture.md` with caching strategy
+3. Update `agents/runbook.md` with Redis setup
+4. Update backlog card with decision
+5. Commit: `[FEAT-XXX] Add Redis caching with ADR`
+
+---
+
+## Navigation Tips
+
+1. **Start here**: If unsure where to look, start with `agents/index.md` (this file)
+2. **API changes**: Always check `agents/api-contracts.md` for rules before modifying API docs
+3. **Data model**: Cross-reference with `api/*.md` modules when updating
+4. **Legacy context**: Check `archive/project_full_legacy.md` for historical decisions if it exists
+5. **Status check**: `${paths.references_dir}/project-status.md` shows current work and blockers
+
+---
+
+## Documentation Size Budget
+
+### File Size Thresholds
+
+| Doc Type | Max Lines | Action When Exceeded |
+|----------|-----------|---------------------|
+| Agent modules (agents/*.md) | 300 | Split into sub-modules |
+| Reference docs (${paths.references_dir}/*) | 300 | Split by topic/collection |
+| API docs | 400 | Split by endpoint group |
+| PRDs/Specs | 500 | Split into requirements + implementation |
+| project-status.md | 200 | Archive to work-history.md |
+
+### When to Split a File
+
+1. File exceeds threshold by 50%+
+2. File mixes doc-types (tutorial + reference + how-to)
+3. File has 3+ distinct topics that could standalone
+4. Agents report context loading issues
+
+### Token Efficiency Guidelines
+
+- Compress verbose cross-references: "See [X](link)." not "See the X documentation for details."
+- Use tables over bullet lists for structured data
+- Remove boilerplate (Purpose/Scope can be 1 line)
+- Link don't duplicate - one source of truth per fact
+
+---
+
+## References
+
+- `${paths.references_dir}/product-scope.md`
+- `${paths.references_dir}/data-model.md`
+- `${paths.references_dir}/api/index.md` (API reference - organize by domain)
+- `${paths.references_dir}/ui/index.md` (UI routes - organize by domain)
+- `${paths.references_dir}/project-status.md`
+- `docs/operations/` (operational procedures - if applicable)
+- `${paths.adrs_dir}/`