mindforge-cc 1.0.0

package/.mindforge/skills/documentation/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: documentation
+version: 1.0.0
+min_mindforge_version: 0.1.0
+status: stable
+triggers: README, docs, documentation, changelog, CHANGELOG, guide, getting started, API docs, comment, JSDoc, docstring, explain, describe
+---
+
+# Skill — Documentation
+
+## When this skill activates
+Any task involving writing or updating documentation, comments, or guides.
+Switch to `tech-writer.md` persona when this skill activates.
+
+## Mandatory actions when this skill is active
+
+### Before writing documentation
+1. Identify the target audience and their goal.
+2. Gather the exact commands or steps to reproduce the task.
+
+### During writing
+- Use clear headings and short paragraphs.
+- Provide working examples where possible.
+- Avoid assumptions about prior knowledge.
+
+### After writing
+- Verify examples and commands are correct.
+- Ensure the document is linked from README or relevant index.
+
+## README.md structure (for every project)
+```markdown
+# Project Name
+
+One sentence that says exactly what this does.
+
+## Quick start
+[Fewest possible steps to get from zero to first value — under 5 minutes]
+
+## Installation
+[Step by step — no assumed knowledge]
+
+## Usage
+[The most common use case with a working code example]
+
+## Commands / API reference
+[Link to docs/commands-reference.md or inline if short]
+
+## Configuration
+[All environment variables with type, default, and description]
+
+## Contributing
+[How to run tests, branch naming, PR process]
+
+## Licence
+```
+
+## Code comment standards
+- Comment WHY, not WHAT. The code shows what. Comments explain intent.
+- ✅ `// We use bcrypt cost 14 here because this is the admin auth path — speed is not critical`
+- ❌ `// Hash the password`
+- Remove TODO comments before committing to main. Create a ticket instead.
+- Every exported function needs a JSDoc/docstring with: description, params, return, throws.
+
+## JSDoc template
+```typescript
+/**
+ * Verifies a JWT access token and returns the decoded payload.
+ *
+ * @param token - The raw JWT string from the Authorization header
+ * @returns Decoded token payload containing userId and role
+ * @throws {TokenExpiredError} If the token has passed its expiry time
+ * @throws {InvalidTokenError} If the token signature is invalid
+ */
+export function verifyAccessToken(token: string): TokenPayload { ... }
+```
+
+## Changelog discipline
+Every user-visible change must appear in CHANGELOG.md before release.
+Format follows Keep a Changelog (keepachangelog.com).
+Categories: Added, Changed, Deprecated, Removed, Fixed, Security.
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Did I read the full SKILL.md before starting? (Not just the triggers)
+- [ ] Did I activate the corresponding persona file?
+- [ ] Did I apply every mandatory action in this skill, not just the ones
+  I remembered off the top of my head?
+- [ ] If this skill produced an output file (review, security report, etc.),
+  has that file been written to the correct path?

package/.mindforge/skills/incident-response/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: incident-response
+version: 1.0.0
+min_mindforge_version: 0.3.0
+status: stable
+triggers: incident, outage, downtime, alert, pagerduty, oncall, on-call, postmortem, post-mortem, runbook, degraded, unavailable, error rate, p0, P0, p1, P1, rollback, hotfix, revert, emergency, spike, anomaly, SLA, SLO, SLI
+---
+
+# Skill — Incident Response Engineering
+
+## When this skill activates
+Any task involving incident runbooks, monitoring setup, alerting configuration,
+hotfixes, rollbacks, or post-incident review documentation.
+
+## Mandatory actions when this skill is active
+
+### Before making changes
+1. Classify severity (P0-P3) and confirm scope of impact.
+2. Locate or create the relevant runbook.
+
+### During incident response
+- Keep a timeline of actions taken and outcomes.
+- Prefer reversible mitigations (rollback, feature flag) before invasive changes.
+- Automated mitigations require explicit human approval for P0/P1 incidents.
+
+### After mitigation
+- Capture root cause and remediation steps.
+- Write or update the postmortem within 48 hours.
+
+## Incident severity classification
+
+| Level | Definition | Response time | Examples |
+|---|---|---|---|
+| P0 (Critical) | Complete service outage affecting all users | Immediate (24/7) | Site down, database unreachable, payment processing failed |
+| P1 (High) | Major feature broken for all/most users | < 15 minutes | Login broken, core feature unavailable |
+| P2 (Medium) | Feature degraded, workaround exists | < 2 hours | Slow API, intermittent errors for subset of users |
+| P3 (Low) | Minor issue, cosmetic or edge case | Next business day | UI glitch, non-critical feature broken |
+
+## Runbook template (write one for every critical path)
+
+File: `docs/runbooks/[service-name]-[issue-type].md`
+
+```markdown
+# Runbook: [Service/Feature] — [Issue Type]
+
+## Overview
+**Service:** [name]
+**Symptom:** [what the monitoring alert describes]
+**Impact:** [who is affected and how]
+**Severity:** P[0-3]
+
+## Detection
+**Alert:** [alert name and source — PagerDuty, Datadog, etc.]
+**Metrics to check:**
+- [metric 1]: normal range [X-Y], alert threshold [Z]
+- [metric 2]: normal range [X-Y], alert threshold [Z]
+
+## Immediate actions (first 5 minutes)
+1. Acknowledge the alert in [alerting tool]
+2. Check [dashboard URL] for current status
+3. [Specific first diagnostic step]
+4. [Specific second diagnostic step]
+5. If confirmed P0/P1: page the on-call lead
+
+## Diagnosis steps
+1. Check [log location] for errors: `grep -E "ERROR|FATAL" [log file] | tail -50`
+2. Check database connectivity: `[connection test command]`
+3. Check external dependencies: `curl -I [dependency health URL]`
+4. Check recent deployments: `git log --oneline -5`
+
+## Mitigation options (in order of preference)
+1. **Restart the service:** `[restart command]` — use if: [condition]
+2. **Scale horizontally:** `[scale command]` — use if: [condition]
+3. **Rollback deployment:** `[rollback command]` — use if: [condition]
+4. **Failover to backup:** `[failover steps]` — use if: [condition]
+5. **Feature flag off:** `[flag command]` — use if: [condition]
+
+## Communication template
+**Internal Slack:** "@oncall [P0] [service] is [symptom]. Investigating. ETA: [X] min"
+**Status page:** "[Service] is currently experiencing [symptom]. We are investigating."
+**Customer email:** [only for P0 lasting > 30 minutes]
+
+## Post-incident (after mitigation)
+1. Update status page: "Resolved. [Brief cause]."
+2. Write postmortem within 48 hours (see template below)
+3. Create follow-up tickets for permanent fix
+
+## Escalation path
+L1 On-call → L2 Senior engineer → L3 Engineering lead → L4 CTO
+Escalate when: unable to mitigate within [X] minutes or if [condition]
+```
+
+## Postmortem template (blameless — always)
+
+File: `docs/postmortems/[YYYY-MM-DD]-[short-title].md`
+
+```markdown
+# Postmortem: [Title]
+**Date of incident:** [ISO-8601]
+**Duration:** [start] → [end] ([X] minutes)
+**Severity:** P[0-3]
+**Author:** [human owner who wrote this]
+**Reviewed by:** [who reviewed]
+**AI assistance:** [if used, list tool and confirm human approval]
+
+## Summary
+[2-3 sentences: what happened, what the impact was, what resolved it]
+
+## Timeline (UTC)
+| Time | Event |
+|---|---|
+| HH:MM | [Alert fired / Issue observed] |
+| HH:MM | [First responder acknowledged] |
+| HH:MM | [Root cause identified] |
+| HH:MM | [Mitigation applied] |
+| HH:MM | [Incident resolved] |
+
+## Root cause
+[One paragraph describing the technical root cause. Factual, no blame.]
+
+## Impact
+- Users affected: [number or percentage]
+- Duration: [X] minutes
+- Data loss: Yes / No (if yes: what data, how much)
+- Revenue impact: [estimate if known]
+- SLA breach: Yes / No
+
+## What went well
+- [Thing 1 that helped: good alert, good runbook, fast diagnosis]
+- [Thing 2]
+
+## What went poorly
+- [Thing 1 that slowed resolution: no runbook, missed alert, unclear owner]
+- [Thing 2]
+
+## Action items
+| Action | Owner | Due date | Priority |
+|---|---|---|---|
+| [Preventive action 1] | [name] | [date] | P[1-3] |
+| [Detection improvement] | [name] | [date] | P[1-3] |
+
+## Lessons learned
+[What systemic changes does this incident motivate?]
+```
+
+## Monitoring standards (write monitoring alongside every feature)
+
+Every new feature must ship with:
+1. **Health check endpoint:** `GET /health` returns 200 when service is operational
+2. **Key metrics instrumented at the service boundary:** request count, error rate, p95 latency, queue depth
+3. **Alerts defined:** at minimum:
+   - Error rate > 1% for 5 minutes → P1 alert
+   - p95 latency > [NFR threshold] for 5 minutes → P2 alert
+   - Zero requests for 5 minutes (if expected traffic) → P1 alert
+4. **Runbook linked in alert:** every alert description links to its runbook
+
+## Hotfix protocol
+
+When a production issue requires an immediate code fix:
+
+```bash
+# 1. Create hotfix branch from production tag
+git checkout -b hotfix/[description] v[last-release-tag]
+
+# 2. Apply the minimal fix — do not add anything else
+# 3. Write or update the test that catches this bug
+# 4. Verify the fix
+npm test
+
+# 5. PR to main AND to the release branch
+# 6. Deploy to production immediately after approval
+# 7. Tag the hotfix release
+git tag -a v[X.Y.Z+1] -m "Hotfix: [description]"
+```
+
+## Self-check before task completion
+- [ ] Severity classified and communicated
+- [ ] Runbook updated or created
+- [ ] Timeline captured in postmortem
+- [ ] Follow-up actions created and assigned

package/.mindforge/skills/performance/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: performance
+version: 1.0.0
+min_mindforge_version: 0.3.0
+status: stable
+triggers: performance, latency, throughput, cache, caching, slow, optimise, optimize, bottleneck, profil, load time, bundle size, memory, CPU, query time, response time, timeout, rate limit, debounce, throttle, memoize, lazy load, code split, tree shake, LCP, CLS, FID, INP, Core Web Vitals, lighthouse
+---
+
+# Skill — Performance Engineering
+
+## When this skill activates
+Any task involving response time, resource usage, bundle size, database query
+performance, or user-perceived load time metrics.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Identify what is being measured. Never optimise without a baseline.
+2. Read the relevant metric from REQUIREMENTS.md (NFRs):
+   - API response time target (e.g., p95 < 200ms)
+   - Page load time target (e.g., LCP < 2.5s)
+   - Bundle size budget (e.g., < 200KB gzipped initial JS)
+3. If no NFR is defined: ask the user to define one before optimising.
+   "Optimisation without a target is premature optimisation."
+
+### Backend performance standards
+
+**Database queries:**
+- Every query must use indexes for its WHERE, JOIN, and ORDER BY columns
+- Detect N+1 queries: if fetching a list then querying per item, use JOIN or batch fetch
+- Pagination: always paginate list endpoints (default page size: 20, max: 100)
+- Avoid `SELECT *` — select only the columns needed
+- Use `EXPLAIN ANALYZE` (PostgreSQL) or `EXPLAIN` (MySQL) to verify query plans
+- Cache repeated identical queries: Redis with appropriate TTL
+
+**API response time:**
+- Default targets (override with NFRs): p50 < 100ms, p95 < 500ms, p99 < 2000ms for most endpoints
+- Slow endpoints (> 500ms): must be async (return immediately, use webhooks or polling)
+- Database connection pooling: always use a connection pool (never open/close per request)
+- Pool sizing: start with `min=2`, `max=CPU * 2 + 2` per instance, then tune to DB limits and workload
+- Serverless: prefer a DB proxy (PgBouncer, RDS Proxy) or driver-level pooling that supports bursty concurrency
+- Avoid synchronous I/O in request handlers
+- Cache hot DB reads at the query or service layer when data is read-heavy and tolerant of staleness
+
+**Caching strategy:**
+Defaults below — tune per data freshness requirements and invalidate on writes.
+| Data type | Recommended cache | TTL |
+|---|---|---|
+| User session data | Redis | 24 hours |
+| Computed aggregates | Redis | 1–5 minutes |
+| Static reference data | Redis | 1 hour |
+| User-specific data | Redis with user key | 15 minutes |
+| API responses | HTTP Cache-Control | depends on freshness needs |
+
+### Frontend performance standards
+
+**Bundle size budgets:**
+| Asset | Budget (gzipped) |
+|---|---|
+| Initial JavaScript | < 200KB |
+| Initial CSS | < 50KB |
+| Per-route chunk | < 100KB |
+| Images (hero) | < 200KB WebP |
+| Fonts | < 50KB per weight |
+
+**Core Web Vitals targets (Google's thresholds):**
+| Metric | Good | Needs improvement | Poor |
+|---|---|---|---|
+| LCP (Largest Contentful Paint) | < 2.5s | 2.5–4s | > 4s |
+| INP (Interaction to Next Paint) | < 200ms | 200–500ms | > 500ms |
+| CLS (Cumulative Layout Shift) | < 0.1 | 0.1–0.25 | > 0.25 |
+
+**Implementation patterns:**
+- Route-based code splitting: every route is its own chunk
+- Lazy load non-critical components: `React.lazy()` + `Suspense`
+- Image optimisation: use `next/image` or equivalent. Always specify `width`/`height`.
+- Font loading: `font-display: swap`. Preload critical fonts.
+- Avoid layout thrashing: batch DOM reads before DOM writes
+- Debounce user input handlers (search: 300ms, resize: 100ms)
+- Memoize expensive computations: `useMemo` / `useCallback` where measured
+
+**SSR/SSG guidance:**
+- Prefer SSG for marketing and content pages with low data volatility
+- Prefer SSR for personalized data, but watch TTFB and cache at the edge where possible
+- For hybrid apps, stream server components or HTML where supported to reduce TTFB and improve LCP
+
+### Performance measurement commands
+
+```bash
+# Backend: measure API response time
+curl -w "@curl-format.txt" -o /dev/null -s https://api.example.com/endpoint
+
+# Frontend: Lighthouse CI
+npx lighthouse https://example.com --output json --output-path ./lighthouse.json
+
+# Bundle analysis
+npx bundle-analyzer stats.json
+
+# Node.js profiling
+node --prof app.js
+node --prof-process isolate-*.log > profile.txt
+
+# Database: explain query
+EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'test@example.com';
+```
+
+## Performance review checklist
+Before marking any task done that involves a query or endpoint:
+- [ ] Query uses appropriate indexes (verified with EXPLAIN)
+- [ ] No N+1 queries in list endpoints
+- [ ] Response time verified locally (curl with timing)
+- [ ] No `SELECT *` in production queries
+- [ ] Caching applied where data is read-heavy and tolerance allows staleness
+
+## Output
+Write performance notes to SUMMARY.md:
+- Baseline metric (before)
+- Achieved metric (after)
+- What optimisation was applied
+- Whether the NFR target was met ✅ or still needs work ⚠️

package/.mindforge/skills/security-review/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: security-review
+version: 1.0.0
+min_mindforge_version: 0.1.0
+status: stable
+triggers: auth, authentication, authorisation, authorization, login, logout, password, token, JWT, session, cookie, OAuth, payment, billing, stripe, PII, GDPR, personal data, upload, file upload, credentials, API key, secret, env, environment variable, encryption, hashing, bcrypt, argon2
+---
+
+# Skill — Security Review
+
+## When this skill activates
+Any task involving user identity, data protection, payments, file handling,
+or credential management. When in doubt: load this skill.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Switch to `security-reviewer.md` persona.
+2. Read the existing code in every file you will touch.
+3. Identify existing vulnerabilities before introducing new ones.
+4. Review SECURITY.md for org-specific policies.
+
+### During implementation
+Apply these patterns by default — do not wait to be asked:
+
+**Authentication**
+- Passwords: bcrypt (cost ≥ 12) or argon2id. Never MD5, SHA1, or unsalted SHA256.
+- Tokens: cryptographically random, minimum 32 bytes. Use `crypto.randomBytes(32)`.
+- JWT: short expiry (15 min access, 7 day refresh). Store refresh in httpOnly cookie.
+- Sessions: regenerate session ID on privilege escalation. Invalidate on logout.
+
+**Authorisation**
+- Check permissions server-side on every request. Never trust client-sent roles.
+- Use deny-by-default. Grant only the minimum required permissions.
+- Log every authorisation failure with user ID, resource, and timestamp.
+
+**Input handling**
+- Validate all input at the boundary (route handler). Reject, never sanitise.
+- SQL: parameterised queries only. Never string concatenation.
+- File uploads: validate MIME type server-side. Never trust `Content-Type` header alone.
+- Redirect URLs: whitelist allowed domains. Never redirect to arbitrary user input.
+
+**Secrets**
+- Environment variables only. Never in source code. Never in git.
+- Rotate credentials if there is any suspicion of exposure.
+- Use a secrets manager (Vault, AWS Secrets Manager) in production.
+
+### After implementation
+Run the OWASP checklist from `security-reviewer.md` against your own diff.
+Write findings to `.planning/phases/phase-N/SECURITY-REVIEW-N.md`.
+
+## Red lines (stop immediately if you encounter these)
+- A hardcoded secret, password, or API key anywhere in the codebase
+- A SQL query built by string concatenation
+- A password comparison using `==` instead of a constant-time function
+- JWT verification being skipped or using `none` algorithm
+- User input being passed directly to `eval()`, `exec()`, or shell commands
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Did I read the full SKILL.md before starting? (Not just the triggers)
+- [ ] Did I activate the corresponding persona file?
+- [ ] Did I apply every mandatory action in this skill, not just the ones
+  I remembered off the top of my head?
+- [ ] If this skill produced an output file (review, security report, etc.),
+  has that file been written to the correct path?
+
+## When you find a vulnerability
+
+Do not silently fix it and move on. For every vulnerability found:
+
+1. **Stop the current task.**
+2. **Classify it** using the severity model (CRITICAL / HIGH / MEDIUM / LOW).
+3. **For CRITICAL or HIGH:** Write to `SECURITY-REVIEW-N.md` immediately.
+   Tell the user. Do not proceed with ANY other work until acknowledged.
+4. **For MEDIUM:** Write to `SECURITY-REVIEW-N.md`. Finish the current task.
+   Flag at the end of the SUMMARY.md.
+5. **For LOW:** Write to `SECURITY-REVIEW-N.md`. Note in SUMMARY.md.
+
+The worst security outcome is a vulnerability that was found, noted mentally,
+and then forgotten when context rolled over. Write it down. Always.

package/.mindforge/skills/testing-standards/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: testing-standards
+version: 1.0.0
+min_mindforge_version: 0.1.0
+status: stable
+triggers: test, tests, spec, unit test, integration test, e2e, coverage, jest, vitest, pytest, mocha, assertion, mock, stub, spy, fixture, TDD
+---
+
+# Skill — Testing Standards
+
+## When this skill activates
+Any task involving writing, running, or improving tests.
+
+## Mandatory actions when this skill is active
+
+### Before writing tests
+1. Identify the exact behavior to verify.
+2. Define the failure condition you expect to prevent.
+
+### During testing
+- Use the AAA pattern with clear separation.
+- Keep tests isolated and deterministic.
+- Cover both happy and error paths.
+
+### After testing
+- Run the full test suite.
+- Record any new tests in SUMMARY.md with paths.
+
+## Coverage targets
+| Test type        | Target  | Measured on               |
+|------------------|---------|---------------------------|
+| Unit             | 80%     | Business logic files only |
+| Integration      | 100%    | All API endpoints         |
+| E2E              | 100%    | Critical user flows       |
+
+## Test structure — AAA pattern (non-negotiable)
+```typescript
+it('should return 401 when token is expired', async () => {
+  // Arrange
+  const expiredToken = generateExpiredToken()
+  const request = buildRequest({ authorization: `Bearer ${expiredToken}` })
+
+  // Act
+  const response = await handler(request)
+
+  // Assert
+  expect(response.status).toBe(401)
+  expect(response.body.error.code).toBe('TOKEN_EXPIRED')
+})
+```
+Blank line between Arrange, Act, and Assert sections. Always.
+
+## Test naming convention
+Pattern: `should [expected behaviour] when [condition]`
+- ✅ `should return 404 when user does not exist`
+- ✅ `should hash password before storing in database`
+- ❌ `user test 4`
+- ❌ `test password`
+
+## Test isolation requirements
+- Every test must be able to run independently in any order
+- No shared mutable state between tests
+- Database state reset between integration tests (use transactions or test containers)
+- External services mocked (HTTP, email, SMS, payment providers)
+- No sleeps or arbitrary timeouts — use proper async patterns
+
+## What to test (and what not to)
+**Test:**
+- Business logic and domain rules
+- Edge cases: null, empty, boundary values
+- Error paths: what happens when dependencies fail
+- Security: auth bypass attempts, injection attempts
+
+**Do not test:**
+- Framework internals (trust the framework)
+- Simple getters/setters with no logic
+- Third-party library behaviour
+
+## File placement
+- Unit tests: co-located with source (`auth.ts` → `auth.test.ts`)
+- Integration tests: `/tests/integration/`
+- E2E tests: `/tests/e2e/`
+- Test utilities/fixtures: `/tests/utils/`
+
+## Before marking any task done
+Run the full test suite. If any test fails: do not commit. Fix it first.
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Did I read the full SKILL.md before starting? (Not just the triggers)
+- [ ] Did I activate the corresponding persona file?
+- [ ] Did I apply every mandatory action in this skill, not just the ones
+  I remembered off the top of my head?
+- [ ] If this skill produced an output file (review, security report, etc.),
+  has that file been written to the correct path?

package/.mindforge/team/TEAM-PROFILE.md

@@ -0,0 +1,42 @@
+# MindForge Team Profile
+# Auto-generated by /mindforge:profile-team
+
+## IMPORTANT: Metrics usage policy
+Per ADR-014, data in this file and `.mindforge/metrics/` is for system
+improvement only, not developer performance evaluation.
+
+Use data for:
+- response personalization
+- skill loading improvements
+- compaction and planning tuning
+- process retrospectives (not people scoring)
+
+## Team composition
+| Name | Email | Primary role | Timezone | Experience |
+|---|---|---|---|---|
+| [Name] | [email] | [role] | [UTC+X] | [level] |
+
+## Tech stack preferences
+| Layer | Preferred | Comfortable | Learning |
+|---|---|---|---|
+| Backend | TypeScript/Node.js | Python | Go |
+| Frontend | React/Next.js | Vue | Svelte |
+| Database | PostgreSQL | MySQL | MongoDB |
+| Testing | Vitest | Jest | Playwright |
+
+## Working patterns
+- Average session length: [N] minutes
+- Peak working hours: [N-N]
+- Verify pass rate: [N%]
+- Common failure type: [from AUDIT]
+
+## Personalization rules
+- Verbosity: concise
+- Review style: direct
+- Preferred code organization: feature-based
+
+## Known strengths
+- [area]
+
+## Known growth areas
+- [area]

package/.mindforge/team/multi-handoff.md

@@ -0,0 +1,23 @@
+# MindForge Team — Multi-Developer HANDOFF
+
+## Purpose
+Allow multiple developers or agent sessions to collaborate without silently
+ stomping shared state.
+
+## Shared coordination rules
+When a developer starts a plan, first check shared `HANDOFF.json` state. If the
+ same plan already appears under `active_developers`, stop and ask for
+ clarification before proceeding.
+
+Developers with `last_seen` older than 4 hours are considered stale and may be
+ removed automatically on the next session start.
+
+## Required shared state fields
+- `active_developers`
+- current phase and plan ownership
+- recent files
+- blockers and decisions needed
+
+## Audit discipline
+Each task completion or failure commit must include any new AUDIT entries so
+ shared history is not stranded in an uncommitted worktree.

package/.mindforge/team/profiles/README.md

@@ -0,0 +1,13 @@
+# MindForge Per-Developer Profiles
+
+Use `PROFILE-[dev-id].md` files to store per-developer preferences and observed
+patterns. `dev-id` is a sanitized email.
+
+Template fields:
+- Identity (name/email/role/timezone)
+- Communication preferences
+- Technical preferences
+- Observed session metrics
+- Strengths and growth areas
+
+Privacy: include only professional, collaboration-relevant data.

package/.mindforge/team/session-merger.md

@@ -0,0 +1,18 @@
+# MindForge Team — Session Merger
+
+## Purpose
+Merge concurrent session state safely after parallel work or multi-developer
+ execution.
+
+## Merge strategy
+1. Merge `HANDOFF.json` through git, not ad hoc overwrite
+2. Resolve conflicts explicitly when two sessions claim the same plan
+3. Preserve both sides' blockers and decisions until reconciled
+4. Keep AUDIT append-only; ensure entries were committed with the task commits
+
+Git merge conflicts are the correct mechanism for contested shared state.
+
+## Conflict rules
+- Same plan claimed by two developers: escalate for human resolution
+- Different plans touching shared files: merge carefully, then rerun verification
+- Stale active developer entry: prune if `last_seen` is older than 4 hours