baldart 3.6.2

package/framework/agents/skills-mapping.md

@@ -0,0 +1,286 @@
+# Skills Mapping
+
+## Purpose
+
+Map Claude Code skills to project domains and provide guidance on when to use each skill.
+
+## Scope
+
+**In**: Skill selection guidance, domain mapping, best practices.
+**Out**: Skill implementation details (see skill documentation).
+
+## Do
+
+- Use skills when appropriate
+- Follow skill-specific guidelines
+- Invoke skills before starting work when applicable
+
+## Do Not
+
+- Skip skills for tasks they're designed for
+- Use wrong skill for the task
+- Rationalize not using applicable skills
+
+## Core Development Skills
+
+### brainstorming
+
+**When to use**:
+
+- Starting new features
+- Unclear requirements
+- Multiple possible approaches
+- Design decisions needed
+
+**Triggers**:
+
+- "Add [feature]"
+- "Build [component]"
+- "Implement [functionality]"
+- "How should I..."
+
+### writing-plans
+
+**When to use**:
+
+- After brainstorming
+- Multi-step implementation needed
+- Complex feature development
+
+**Triggers**:
+
+- After design approval
+- Before starting implementation
+- For documented requirements
+
+### test-driven-development
+
+**When to use**:
+
+- Implementing new features
+- Fixing bugs
+- Adding testable functionality
+
+**Triggers**:
+
+- New feature implementation
+- Bug fix with test case
+- Refactoring with tests
+
+### systematic-debugging
+
+**When to use**:
+
+- Bug investigation
+- Test failures
+- Unexpected behavior
+
+**Triggers**:
+
+- "Fix [bug]"
+- "Why is [X] not working?"
+- Test failure analysis
+
+## Code Quality Skills
+
+### code-review
+
+**When to use**:
+
+- Before merging
+- After major implementation
+- PR review process
+
+**Triggers**:
+
+- Feature completion
+- Before deployment
+- Pull request review
+
+### verification-before-completion
+
+**When to use**:
+
+- Claiming work is complete
+- Before marking card done
+- Before creating PR
+
+**Triggers**:
+
+- "Done"
+- "Fixed"
+- "Tests passing"
+
+## UI/UX Skills
+
+### frontend-design
+
+**When to use**:
+
+- Building UI components
+- Creating pages
+- Styling work
+
+**Triggers**:
+
+- "Create [page]"
+- "Build [component]"
+- "Design [interface]"
+
+### ui-ux-pro-max
+
+**When to use**:
+
+- Professional UI/UX design
+- Design system work
+- Polished interfaces
+
+**Triggers**:
+
+- Design-heavy features
+- Visual refinement needed
+- Design system development
+
+## Testing Skills
+
+### playwright-skill
+
+**When to use**:
+
+- Browser automation
+- E2E testing
+- UI testing
+
+**Triggers**:
+
+- "Test [page]"
+- "Automate [flow]"
+- Visual regression testing
+
+### webapp-testing
+
+**When to use**:
+
+- Full webapp testing
+- Server lifecycle management
+- Comprehensive test orchestration
+
+**Triggers**:
+
+- Full application testing
+- Integration testing
+- Server management needed
+
+## Documentation Skills
+
+### writing-clearly-and-concisely
+
+**When to use**:
+
+- Writing documentation
+- Creating specs
+- User-facing content
+
+**Triggers**:
+
+- Documentation updates
+- README writing
+- Technical writing
+
+## Project-Specific Skills
+
+Add your project-specific skills here:
+
+### [Your Skill 1]
+
+**When to use**: [Description]
+**Triggers**: [When to invoke]
+
+### [Your Skill 2]
+
+**When to use**: [Description]
+**Triggers**: [When to invoke]
+
+## Skill Selection Decision Tree
+
+```
+START: User gives a task
+  |
+  v
+Is it a new feature/design task?
+  |-- YES --> Use brainstorming skill first
+  |           Then writing-plans
+  |           Then implementation skills
+  |
+  v
+Is it a bug fix?
+  |-- YES --> Use systematic-debugging
+  |           Then test-driven-development
+  |           Then verification-before-completion
+  |
+  v
+Is it UI/visual work?
+  |-- YES --> Use frontend-design or ui-ux-pro-max
+  |
+  v
+Is it browser testing?
+  |-- YES --> Use playwright-skill or webapp-testing
+  |
+  v
+Is work complete?
+  |-- YES --> Use verification-before-completion
+  |           Then code-review
+  |
+  v
+Proceed with appropriate skill
+```
+
+## Skill Chaining
+
+Common skill chains:
+
+1. **New Feature**:
+   - brainstorming → writing-plans → test-driven-development → verification-before-completion → code-review
+
+2. **Bug Fix**:
+   - systematic-debugging → test-driven-development → verification-before-completion
+
+3. **UI Feature**:
+   - brainstorming → frontend-design → test-driven-development → playwright-skill → code-review
+
+4. **Refactoring**:
+   - code-review (identify issues) → test-driven-development → verification-before-completion
+
+## Anti-Patterns
+
+**Don't**:
+
+- Skip brainstorming for "simple" features
+- Start coding before planning
+- Skip TDD because "I know how to fix it"
+- Skip verification before claiming completion
+- Use wrong skill for the task
+
+**Do**:
+
+- Follow skill workflows
+- Chain skills appropriately
+- Use skills even when they seem "overkill"
+- Trust the skill process
+
+## Skill Configuration
+
+Some skills may require configuration:
+
+- [Skill-specific config location]
+- [Environment variables needed]
+- [Setup requirements]
+
+## Custom Skills
+
+Document how to create custom skills:
+
+1. Create skill file in `.claude/skills/`
+2. Follow skill template format
+3. Document when to use
+4. Add to this mapping file

package/framework/agents/testing.md

@@ -0,0 +1,111 @@
+# Testing
+
+## Purpose
+
+Define required manual testing and QA issue workflow, including browser automation.
+
+## Scope
+
+**In**: Manual testing steps, QA issue creation and handling, browser automation.
+**Out**: Performance testing strategy (see agents/performance.md).
+
+## Do
+
+- Run project build command before marking a card done.
+- Manually test changed flows in development environment.
+- Record results in the backlog card.
+
+## Do Not
+
+- Close QA issues after a fix (leave open with `vibe review`).
+
+## Manual Testing Protocol (MVP)
+
+1. Run test suite when tests exist.
+2. Run build command (must pass).
+3. Run development server and manually test changed flows.
+4. Record results in card notes.
+
+## Manual Test Checklist
+
+- Happy path works end-to-end
+- Error cases handled gracefully
+- Loading states shown
+- Mobile viewport tested (for UI changes)
+- Authentication/authorization works
+- No console errors in browser/logs
+
+## Browser Automation Testing (if applicable)
+
+For UI/frontend changes, consider using browser automation tools (e.g., Playwright, Cypress, Selenium):
+
+### When to Use Browser Automation
+
+- Testing user flows (login, checkout, form submissions)
+- Validating responsive design across viewports
+- Capturing screenshots for visual regression
+- Checking browser console for errors
+- Verifying loading states and animations
+- Testing accessibility (tab navigation, focus states)
+
+### Browser Test Examples
+
+**Test a page across viewports:**
+
+```
+Test the dashboard page at desktop (1920x1080),
+tablet (768x1024), and mobile (375x667) viewports
+```
+
+**Test authentication flow:**
+
+```
+Test the login flow: fill credentials, submit,
+verify redirect to dashboard
+```
+
+**Capture screenshots:**
+
+```
+Capture full-page screenshots of the marketing page
+at desktop and mobile sizes
+```
+
+## QA Issue Methodology (Manual)
+
+- One GitHub issue per test case (atomic scope).
+- Labels: `qa` + one macro area (customize for your project - e.g., `area:frontend`, `area:api`, `area:admin`).
+- When a GitHub issue is fixed: add a fix summary comment, apply `vibe review`, leave it open.
+- If a test passes: leave the issue open with a short note.
+- If a test fails: keep it open with details and evidence.
+- Open QA issues are the source of truth for unresolved bugs.
+
+### QA Evidence
+
+When creating or updating QA issues:
+
+- Include reproduction steps
+- Attach screenshots/videos if visual bugs
+- Note environment details (browser, viewport, OS)
+- Include error logs/console output if relevant
+- Add test scripts that reproduce the issue (if using automation)
+
+## Test Coverage (if applicable)
+
+- [Define coverage requirements - e.g., minimum 80% coverage]
+- [Critical paths requiring 100% coverage]
+- [Areas exempt from coverage requirements]
+
+## Test Organization
+
+- [Test file location conventions]
+- [Test naming conventions]
+- [Integration vs unit test guidelines]
+- [End-to-end test guidelines]
+
+## Continuous Integration
+
+- [CI test requirements]
+- [When tests run (pre-commit, pre-push, PR)]
+- [Test failure handling policy]
+- [Flaky test management]

package/framework/agents/workflows.md

@@ -0,0 +1,215 @@
+# Workflows
+
+## Purpose
+
+Define how agents plan, track, and complete work safely.
+
+## Scope
+
+**In**: Backlog workflow, Active Code Context, handoffs, conflict resolution, commits.
+**Out**: Testing specifics (see agents/testing.md).
+
+## Do
+
+- Work from a single backlog card at a time.
+- Keep Active Code Context updated before and after changes.
+
+## Do Not
+
+- Start work without a card or without setting context.
+
+## Violations (Invalid Work)
+
+- Code change without doc update is invalid.
+- Doc update without code implementation is incomplete.
+- Work without a backlog card is unauthorized.
+
+## Backlog Workflow
+
+1. List cards in `${paths.backlog_dir}/*.yml`.
+2. Select one card with status `TODO` or `READY`.
+3. Set card to `IN_PROGRESS`, assign yourself, and set `execution_mode` (`local` or `cloud`).
+4. Claim ownership for touched areas via `claimed_paths` in the card.
+5. Update `${paths.references_dir}/project-status.md` -> Active Code Context.
+
+## During Work
+
+- Update card tasks and notes as you go.
+- Record unknowns and assumptions in the card.
+- Do not touch files claimed by another in-progress card.
+
+## Finish Work
+
+1. Verify Definition of Done in the card.
+2. Set status to `DONE` (or `BLOCKED`).
+3. Update `${paths.references_dir}/project-status.md` (Current Status, Known Issues, Active Code Context).
+4. Add ADRs for architectural decisions.
+
+## Status Tracking
+
+- Valid statuses: `TODO`, `READY`, `IN_PROGRESS`, `BLOCKED`, `DONE`.
+- `IN_PROGRESS` requires Active Code Context set.
+- `BLOCKED` requires blocker documented in card and status file.
+
+## Deploys and Publications
+
+- Production deploys and publications must follow `agents/deployment-protocol.md` if it exists.
+- Treat deploy work as backlog-driven work with full testing gates and documented rollback intent.
+
+## Handoff Protocol
+
+Use Active Code Context format from `${paths.references_dir}/project-status.md` and set Status to `HANDOFF_READY`.
+Record `handoff.from`, `handoff.to`, `handoff.summary`, and `handoff.next_steps` in the card.
+The receiver must acknowledge, keep claims aligned, and set `IN_PROGRESS`.
+
+## Unknowns and Assumptions
+
+- Missing info: mark UNKNOWN in the backlog card and ask the user.
+- Assumptions: mark ASSUMED with rationale, and add an ADR if permanent.
+
+## Forbidden Assumptions
+
+- Switching external providers without ADR.
+- Switching Auth providers without ADR.
+- Changing database structure without updating data model reference.
+- Adding external dependencies without documentation.
+- Changing API contracts without updating API reference.
+
+## Conflict Resolution
+
+1. Stop if docs conflict with code.
+2. Determine which is newer and update the other.
+3. Record the resolution in an ADR.
+
+## Commit Hygiene
+
+- Commit format: `[FEAT-XXX] Brief description` or adapt to your project convention.
+- Keep commits small and traceable.
+- Do not commit without updated docs.
+
+Example:
+```
+[FEAT-001] Add user management endpoints
+
+- Created /api/users endpoints (GET, POST, PATCH, DELETE)
+- Updated ${paths.references_dir}/data-model.md
+- Added users to seed script
+```
+
+## Pre-commit Hooks (Automated Quality Gates)
+
+**What Runs**: Every commit should trigger automated checks via git hooks (e.g., Husky + lint-staged):
+
+1. **Linting**: Auto-fix + zero-warnings on staged files
+2. **Type Checking**: Type-check entire project (if applicable)
+3. **Format Checking**: Auto-fix formatting on staged files
+4. **Fast Build Check**: Quick compilation/type check without full build
+
+**Timing**: Target <10 seconds (optimized for speed)
+
+**Enforcement**: BLOCKING - Commit fails if any check fails
+
+### When Checks Fail
+
+1. **Review the error output** - Pre-commit hooks show exactly what failed
+2. **Fix the issue** - Most common:
+   - Linting errors: Run your lint command to see full report
+   - Type errors: Check file and line number in error output
+   - Format errors: Run your format command
+   - Build errors: Run your build command for detailed trace
+3. **Retry commit** - Hooks run again automatically
+
+### Emergency Bypass (Use Sparingly)
+
+**When to use**:
+
+- Emergency hotfix needed immediately
+- External blocker (CI down, registry issues)
+- Working on draft/WIP commit that will be amended
+
+**How to bypass**:
+
+```bash
+git commit --no-verify -m "[EMERGENCY] Brief reason for bypass"
+```
+
+**Rules**:
+
+- Document reason in commit message
+- Fix issues in next commit
+- Add note to backlog card explaining bypass
+
+**Example valid bypass**:
+
+```bash
+git commit --no-verify -m "[EMERGENCY] Hotfix production outage - will fix linting in next commit"
+```
+
+**Example invalid bypass**:
+
+```bash
+git commit --no-verify -m "wip"  # ❌ No reason, not emergency
+```
+
+### Troubleshooting
+
+**Issue**: Hook takes >10 seconds
+- **Cause**: Large number of staged files or slow type checking
+- **Fix**: Commit smaller batches, or optimize type checking configuration
+
+**Issue**: Hook fails on files that look correct
+- **Cause**: Linter/formatter rules are strict
+- **Fix**: Follow linter suggestions or configure rules if too strict
+
+**Issue**: Type error in file I didn't touch
+- **Cause**: Type checking checks whole project (type dependencies)
+- **Fix**: Fix the error or bypass if unrelated to your work (then fix separately)
+
+## Repo State and Branch Hygiene (MUST)
+
+Follow this protocol to prevent local/remote drift.
+
+## Pre-Work Sync
+
+1. Run `git fetch origin`.
+2. Run `git status -sb` and verify a clean working tree.
+3. Confirm you are on the intended branch.
+4. Sync from `origin/main` with fast-forward policy (`git pull --ff-only`) when required by your mode.
+
+## Destructive Operations (Owner Approval Required)
+
+- Force push, reset, or branch deletion requires explicit owner approval and a backlog note.
+- Before destructive changes, create a safety tag:
+  - `git tag backup/<YYYYMMDD>-<reason>` and note it in the card.
+
+## Branch Policy (Mode-Based)
+
+- `local` mode: may work on `main` only with owner approval.
+- `cloud` mode: always create branch-per-card from `main` (`codex/<CARD-ID>-<slug>` or `claude/<CARD-ID>-<slug>`).
+- Cloud agents must never commit directly to `main`; PR review + green CI are required before merge.
+- Delete merged feature branches only when owner instructs.
+
+## Post-Work Sync
+
+1. Ensure `git status -sb` is clean.
+2. Push your working branch and open/update PR with test evidence.
+3. Merge to `main` is owner-controlled after approval and CI success.
+4. If instructed, prune remote branches.
+
+## Testing Gates (Mode-Based)
+
+- Required for all modes: run tests (if exist), run build, pre-commit hooks, and passing CI checks.
+- `local` mode: manual validation is mandatory and must be logged in card notes.
+- `cloud` mode: manual validation is advisory unless explicitly requested; prefer CI and automated checks.
+
+## Provider Changes (ADR Required)
+
+- External provider changes.
+- Auth provider changes.
+- Database changes.
+- External API or deployment target changes.
+
+## Emergency Protocols
+
+- If blocked: set card to `BLOCKED`, record blocker, update status file, ask user.
+- If context lost: read AGENTS + project-status + your card, then ask for priority.