contextos-agents 2.2.0 → 2.3.1

package/.agents/core/skills/engineering-workflow/references/workflow.md

@@ -0,0 +1,336 @@
+
+# engineering-workflow
+
+## Overview
+
+Systematic 6-phase engineering pipeline (DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP) enforcing role declarations, atomic task execution, quality gates, regression prevention, and structured requirements elicitation.
+
+## When to Use
+
+Activate on all project tasks to orchestrate structured development, spec definition, architectural planning, and verification gates.
+
+## Rules & Patterns
+
+Inspired by [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) by Addy Osmani (Google Chrome) and [obra/superpowers](https://github.com/obra/superpowers).
+
+### Core Principle
+
+> **A junior writes code immediately. A senior writes a spec first.**\
+> Establish scope before substantial changes and carry existing authorization forward.
+
+---
+
+### The 6-Phase Development Pipeline
+
+```
+  DEFINE          PLAN           BUILD          VERIFY         REVIEW          SHIP
+ ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐
+ │ Idea │ ───▶ │ Spec │ ───▶ │ Code │ ───▶ │ Test │ ───▶ │  QA  │ ───▶ │  Go  │
+ │Refine│      │  PRD │      │ Impl │      │Debug │      │ Gate │      │ Live │
+ └──────┘      └──────┘      └──────┘      └──────┘      └──────┘      └──────┘
+   /spec          /plan          /build        /test         /review       /ship
+
+[ROLE: Product Manager]  [ROLE: Architect]  [ROLE: Senior Dev]  [ROLE: QA Lead]  [ROLE: Staff Eng]  [ROLE: Release Eng]
+```
+
+**Workflow rule**: Scope substantial work before implementation. Existing authorization, standalone requests, and routine fast tracks permit proceeding directly.
+**Direct Build & Fast-Track Exception**: When the prompt/caller explicitly requests a standalone implementation, declares `[PHASE: Build]`, or requests routine operational/maintenance tasks (git operations, version bumps, typo fixes, small config tweaks, diagnostic checks), proceed directly to execution without conversational approval pauses.
+
+---
+
+### Phase 1: DEFINE - /spec
+
+**Auto-activates → `[ROLE: Product Manager]`**
+
+Turn vague intent into a precise, executable specification.
+
+#### Step 1.1: The Interview Protocol (`interview-me`)
+
+Before writing the spec, if there is ambiguity, high blast radius, or multiple architectural paths, stop and ask the user **one question at a time** (or up to 2 tightly coupled questions):
+
+1. **Clarify Business Intent**: What user problem are we solving? What is explicitly out of scope?
+2. **Clarify Constraints**: Runtime versions, database engines, performance bounds.
+3. **Clarify Edge Cases**: What happens on offline state, empty lists, unauthorized requests?
+
+#### Step 1.2: Spec Template
+
+```markdown
+## Feature Spec: [Feature Name]
+
+### Why (Problem)
+[What pain does this solve? Who has it? How often?]
+
+### Scope (What's In / Out)
+
+**In-Scope**:
+- [Specific item 1]
+- [Specific item 2]
+
+**Out-of-Scope**:
+- [Thing we're NOT doing and why]
+
+### Technical Approach
+[Read the relevant code. Understand what changes where.]
+Files affected:
+- `src/X.js` - [what changes]
+- `src/Y.js` - [what changes]
+
+### Acceptance Criteria
+- [ ] Given [context], when [action], then [result]
+- [ ] Given [context], when [action], then [result]
+
+### Open Questions
+- [Unresolved decision 1]
+- [Unresolved decision 2]
+```
+
+---
+
+### Phase 2: PLAN - /plan
+
+**Auto-activates → `[ROLE: Architect]`**
+
+Break the spec into atomic, independently testable tasks.
+
+#### Thin Vertical Slices (`incremental-implementation`)
+
+Organize tasks as **Thin Vertical Slices** rather than horizontal layers:
+
+- **Bad (Horizontal)**: Task 1: All DB migrations. Task 2: All API routes. Task 3: All UI components. (Nothing works until step 3).
+- **Good (Vertical Slices)**: Slice 1: Minimal DB table + minimal API + minimal UI button end-to-end. Verify and commit. Slice 2: Add validation + edge cases. Slice 3: Polish UI & telemetry.
+
+#### Plan Rules
+
+- Each task must be **completable in < 2 hours** of focused work.
+- Each task must be **independently testable**.
+- Tasks must be **ordered by dependency** (blocking tasks first).
+- Each task gets a **test requirement** - no task without a test.
+
+#### Plan Template
+
+```markdown
+## Implementation Plan: [Feature Name]
+
+### Tasks
+
+**Task 1: [Slice 1 Name]** (est. 30min)
+- What: [Specific implementation detail]
+- Files: [file1.js, file2.js]\
+- Test: [How will you verify this works?]
+- Blocked by: [nothing / Task N]
+
+**Task 2: [Slice 2 Name]** (est. 45min)
+- What: [Specific implementation detail]
+- Files: [file3.js]
+- Test: [Test description]
+- Blocked by: Task 1
+
+### Risk Assessment
+- [Risk 1]: [Mitigation]
+- [Risk 2]: [Mitigation]
+
+### STOP - Awaiting Approval
+Proceed to BUILD when implementation is authorized; clarify missing scope decisions when needed.
+```
+
+---
+
+### Phase 3: BUILD - /build
+
+**Auto-activates → `[ROLE: Senior Developer]`**
+
+Implement one task at a time. Commit after each task.
+
+#### Build Rules
+
+1. **One task per commit** - atomic, descriptive commit messages.
+2. **Write the test FIRST** (TDD - red-green-refactor).
+3. **No dead code** - if it's not tested, it's not shipped.
+4. **No TODOs in committed code** - resolve or create a tracked issue.
+5. **Read before writing** - understand the surrounding code before changing it.
+6. **Limit the blast radius** - modify ONLY the files explicitly listed in the current task's plan. Do NOT rewrite adjacent components, hooks, or utilities unless strictly required by the authorized outcome.
+
+#### Commit Message Format
+
+```text
+type(scope): short description (max 72 chars)
+
+- Detail 1
+- Detail 2
+
+Refs: #issue-number
+```
+
+Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
+
+---
+
+### Phase 4: VERIFY - /test
+
+**Auto-activates → `[ROLE: QA Lead]`**
+
+Tests are proof, not an afterthought.
+
+#### Test Strategy by Code Type
+
+**Logic & Services (TDD)**:
+
+```text
+1. RED:      Write a failing test for the next small behavior
+2. GREEN:    Write the minimum code to make it pass
+3. REFACTOR: Clean up without breaking tests
+4. REPEAT
+```
+
+**UI Components & User Flows (BDD)**:
+
+For complex React components, prioritize testing _user behavior_ over internal state:
+
+- Use **React Testing Library** (`userEvent`, `screen.getByRole`) - test what the user sees.
+- Use **Playwright** for critical user flows (login, checkout, form submit).
+- Do NOT test implementation details (internal state, private methods, component structure).
+- Focus on: "When user clicks X, does Y appear?" not "Does `useState` hold the right value?"
+
+```tsx
+// [GOOD] BDD: Test behavior
+test("shows error when email is invalid", async () => {
+  render(<LoginForm />);
+  await userEvent.type(screen.getByLabelText("Email"), "not-an-email");
+  await userEvent.click(screen.getByRole("button", { name: /sign in/i }));
+  expect(screen.getByText(/invalid email/i)).toBeInTheDocument();
+});
+```
+
+#### Test Quality Gates
+
+Before moving to Review, verify:
+
+- [ ] All new code has tests
+- [ ] Tests are meaningful (not just coverage theater)
+- [ ] Edge cases are covered (null, empty, overflow, unauthorized)
+- [ ] Tests fail when the implementation is broken (anti-regression)
+- [ ] Test names are readable: `it("returns 404 when user not found")`
+
+---
+
+### Phase 5: REVIEW - /review
+
+**Auto-activates → `[ROLE: Staff Engineer]` + `[ROLE: Senior Designer]` for UI tasks**
+
+Review before merging. Always.
+
+#### Subagent / Peer Code Review Protocol
+
+Inspired by [obra/superpowers](https://github.com/obra/superpowers):
+
+1. **Self-Review First**: The implementer runs git diff and verifies against the original acceptance criteria.
+2. **Review Checklist**:
+   - **Correctness**: Does it do what the spec says? Are all criteria met?
+   - **Architecture**: Single Responsibility, DRY without premature abstraction, no business logic in API routes.
+   - **Security**: No secrets hardcoded, inputs validated via Zod/schemas, auth checked before data access.
+   - **Performance**: No N+1 queries, expensive operations cached, sets paginated.
+   - **Design**: If UI, passes `impeccable-design` quick audit (typography, colors, spacing, animations).
+
+---
+
+### Phase 5.5: SIMPLIFY - /simplify
+
+**Auto-activates → `[ROLE: Staff Engineer]` (Ponytail Mindset)**
+
+Before merging, ruthlessly simplify:
+
+1. Did we introduce abstractions that are only used once? (Inline them).
+2. Can 3 lines of standard JavaScript replace a 50-line custom utility?
+3. Is any configuration or generic handler premature? (YAGNI).
+4. Is the code obvious to a mid-level engineer without reading a documentation manual?
+
+---
+
+### Phase 6: SHIP - /ship
+
+**Auto-activates → `[ROLE: Release Engineer]`**
+
+Only ship when all gates are green.
+
+#### Pre-Ship Checklist
+
+- [ ] All tests pass in CI
+- [ ] No lint errors
+- [ ] Feature works in staging environment
+- [ ] Docs updated (README, API docs, changelogs)
+- [ ] Breaking changes documented
+- [ ] Rollback plan exists
+- [ ] Preview / staging deployment verified (if applicable, e.g. Vercel Preview and Core Web Vitals for frontend deployments)
+
+#### Operational Self-Improvement
+
+Before completing a workflow, review the session for durable learnings. Write them to `.agents/learnings.md`. If no durable learning occurred, state "No durable learnings this session" in your final output.
+
+---
+
+## Code Examples
+
+### Vertical Slice Example
+
+```javascript
+// Slice 1: Minimal functional endpoint
+// POST /api/v1/projects -> creates project with basic validation
+import { z } from 'zod';
+import { projectService } from '@/services/project';
+
+const CreateProjectSchema = z.object({
+  name: z.string().min(1).max(100),
+  description: z.string().optional()
+});
+
+export async function POST(req) {
+  const session = await auth();
+  if (!session?.userId) return Response.json({ error: 'Unauthorized' }, { status: 401 });
+
+  const body = await req.json();
+  const parsed = CreateProjectSchema.parse(body);
+  const project = await projectService.create({ ...parsed, userId: session.userId });
+
+  return Response.json(project, { status: 201 });
+}
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Specification exists with clear In-Scope and Out-of-Scope boundaries.
+- [ ] Implementation plan broken down into vertical tasks < 2 hours each.
+- [ ] Tests written before implementation (TDD/BDD).
+- [ ] Code reviewed against correctness, security, performance, and design gates.
+- [ ] Staged security and quality check passes (`contextos scan --staged --enforce`).
+- [ ] Simplification ladder executed before shipping.
+
+---
+
+## Common Mistakes
+
+- **Writing code before approval**: Skipping `/spec` or `/plan` in interactive sessions.
+- **Horizontal task splitting**: Building all DB models first without verifying end-to-end integration.
+- **Premature refactoring**: Changing unrelated adjacent code during a feature task.
+- **Ignoring non-happy paths**: Testing only 200 OK responses while ignoring 400, 401, 404, 500 scenarios.
+
+---
+
+## Integration Notes
+
+- Integrates with `gstack-roles` for automated role switching across all 6 phases.
+- Triggers `ponytail-mindset` during the BUILD and SIMPLIFY phases.
+- Hands off to `impeccable-design` for UI quality review.
+- Coordinates with `security` during Phase 5 for pre-merge compliance.
+
+---
+
+## Completion Status Protocol
+
+When completing a task or workflow, you must explicitly report your final status as the last part of your output:
+
+- **DONE** - completed with evidence.
+- **DONE_WITH_CONCERNS** - completed, but list concerns.
+- **BLOCKED** - cannot proceed; state blocker and what was tried.
+- **NEEDS_CONTEXT** - missing info; state exactly what is needed.

package/.agents/core/skills/engineering-workflow/skill.yaml

@@ -1,13 +1,11 @@
 schemaVersion: 2
 name: engineering-workflow
 type: instruction-only
-description: >
-  Senior engineering workflow skill inspired by Addy Osmani's agent-skills.
-  Enforces the full development lifecycle: spec → plan → build → test → review → ship.
-  AI must never write code before a spec and plan are approved.
+description: Scope implementation work, verify behavior, and report evidence using a proportional lifecycle.
 version: 1.0.0
 resources:
   - EXAMPLES.md
   - SKILL.md
   - TROUBLESHOOTING.md
   - VALIDATION.json
+  - references/workflow.md

package/.agents/core/skills/gstack-roles/SKILL.md

@@ -1,155 +1,38 @@
 ---
 name: gstack-roles
-description: >
-  Role-based AI specialist system. Defines 23 specialist roles and teaches the AI
-  to adopt the correct role before each task phase, like a virtual engineering team.
+description: Compatibility alias for engineering-workflow with optional specialist review perspectives.
 ---
 
 # gstack-roles
 
 ## Overview
 
-Specialist persona orchestrator defining 23 domain roles (Product Manager, Architect, Senior Developer, QA Lead, Chief Security Officer, etc.). Enforces mindset transitions across engineering pipeline phases.
+Use specialist perspectives when they reveal concrete issues. The canonical lifecycle skill is engineering-workflow.
 
 ## When to Use
 
-Activate on every task to declare explicit specialist role and mindset before beginning DEFINE, PLAN, BUILD, VERIFY, REVIEW, or SHIP phases.
+Explicit role guidance or a specialist review request.
 
 ## Rules & Patterns
 
-Inspired by [Garry Tan's gstack](https://github.com/garrytan/gstack) - structured persona transitions across engineering phases.
-
-## Core Principle
-
-> Before starting ANY task, identify your current role. You are not a generic AI. You are a specialist. Think and act accordingly.
-
-## Role Identification Protocol
-
-At the start of each task or major phase switch, declare your role using the ContextOS standard format:
-
-```text
-[DOMAIN: <Domain>] [PHASE: <Phase>] [ROLE: <Role Name>]
-Skills loaded: <skill-1>, <skill-2>
-```
-
-> **Anti-Spam Invariant**: Declare this role header **strictly once per phase**. Never prefix intermediate tool calls, file operations, or step updates with role tags.
-
-Then execute ONLY within the constraints of that role.
-
----
-
-## The 23 Specialist Roles
-
-### Strategy & Planning
-
-| Role | Mandate | When to Activate |
-| ------ | --------- | ----------------- |
-| **CEO / Founder** | Rethink the problem. Find the 10-star product hiding inside the request. Challenge scope. | Feature planning, product decisions |
-| **YC Office Hours** | Ask 6 forcing questions that reframe the product before writing code. Push back on framing. | Before any new feature starts |
-| **Product Manager** | Define requirements as user stories. Prioritize ruthlessly. Ship the narrowest wedge first. | Requirement gathering |
-| **Architect** | Lock in architecture, data flow, diagrams, edge cases. Force hidden assumptions into the open. | System design, tech stack decisions |
-
-### Engineering
-
-| Role | Mandate | When to Activate |
-| ------ | --------- | ----------------- |
-| **Engineering Manager** | Break work into atomic tasks. Review test plans. Run retrospectives. | Sprint planning, reviews |
-| **Staff Engineer** | Find bugs that pass CI but blow up in production. Auto-fix the obvious. Flag gaps. | Code review |
-| **Senior Developer** | Write production-quality code. Follow architecture decisions. Test everything. | Implementation |
-| **Debugger** | Systematic root-cause debugging. Iron Law: no fixes without investigation. | Bug fixing |
-| **Performance Engineer** | Baseline metrics. Core Web Vitals. Resource sizes. Compare before/after. | Optimization |
-| **Developer Experience Lead** | Benchmark onboarding speed. Find friction. Design the magical moment. | DX review |
-
-### Design
-
-| Role | Mandate | When to Activate |
-| ------ | --------- | ----------------- |
-| **Senior Designer** | Rate each design dimension 0-10. Detect AI slop. Interactive: one question per design choice. | Design review, UI tasks |
-| **Design Engineer** | Turn mockups into production HTML/CSS that actually works. 30KB, zero deps where possible. | Frontend implementation |
-| **Design Explorer** | Generate 4-6 design variants. Open comparison. Iterate until user loves it. | Design ideation |
-
-### Quality & Security
-
-| Role | Mandate | When to Activate |
-| ------ | --------- | ----------------- |
-| **QA Lead** | Test the app, find bugs, fix with atomic commits, re-verify, write regression tests. | Before shipping |
-| **QA Reporter** | Pure bug report only. No code changes. | Bug reporting |
-| **Chief Security Officer** | OWASP Top 10 + STRIDE threat model. Zero-noise: 8/10+ confidence gate. Each finding needs exploit scenario. | Security audit |
-
-### Operations & Release
-
-| Role | Mandate | When to Activate |
-| ------ | --------- | ----------------- |
-| **Release Engineer** | Sync main, run tests, audit coverage, push, open PR. Bootstrap test frameworks if missing. | Before shipping |
-| **SRE** | Post-deploy monitoring loop. Watch for console errors, performance regressions, failures. | After deploy |
-| **Technical Writer** | Update all docs to match what shipped. Catch stale READMEs. Build Diataxis coverage map. | After feature ships |
-
-### Research & Memory
-
-| Role | Mandate | When to Activate |
-| ------ | --------- | ----------------- |
-| **Researcher** | Investigate root causes systematically. No fixes without understanding. Max 3 hypothesis cycles. | Unknown problems |
-| **Memory Manager** | Manage learnings across sessions. Review, search, prune, export project patterns. | Session start/end |
-| **Spec Author** | Turn vague intent into precise executable specs in 5 phases: why, scope, technical, draft, file. | Before planning |
-| **Retro Facilitator** | Per-person breakdowns, shipping streaks, test health trends, growth opportunities. | End of sprint |
-
----
-
-## Sprint Lifecycle
-
-Every change follows this lifecycle, with a specific role per phase:
-
-```
-THINK          PLAN           BUILD          REVIEW         TEST           SHIP
-[YC Hours]   [Architect]   [Sr Developer]  [Staff Eng]   [QA Lead]    [Release Eng]
-[CEO]        [Eng Mgr]                     [Designer]    [Sec Officer]
-```
-
-## Role-Switching Rules
-
-1. **Never skip phases.** Don't jump from "idea" to "write code."
-2. **One role at a time.** Don't mix QA and implementation in the same response.
-3. **Declare before acting.** Always state `[ROLE: X]` before switching modes.
-4. **Escalate correctly.** If a QA finds an architectural problem → escalate to Architect role.
-5. **The CEO always goes last on planning** - challenges scope reduction before committing.
-
-## Example Usage
-
-```
-User: "Add a notifications feature"
-
-[ROLE: YC Office Hours]
-Before I plan this, 6 forcing questions:
-1. What pain does the ABSENCE of notifications cause today?
-2. Who specifically gets notified? What's the trigger?
-...
-
-[ROLE: CEO / Founder]
-I'm going to push back on "notifications feature." 
-What you actually described is a user re-engagement system.
-The narrowest wedge: one email on task completion.
-Ship that tomorrow. The full vision is a 3-month project.
-
-[ROLE: Architect]
-For the narrow wedge:
-- Event: task.completed → webhook → email queue (Redis)
-- No real-time needed for MVP
-- Schema: notifications(id, user_id, type, payload, sent_at)
-```
+Choose the useful perspective: product scope, architecture, implementation, QA, security, or release. Role declarations are optional. Repeated headers and mandatory role switches add no evidence. Existing authorization and routine fast tracks apply.
 
+Read [references/roles.md](references/roles.md) for detailed procedures and examples only when needed.
 
 ## Code Examples
 
-See `EXAMPLES.md` for detailed code examples.
+For access control, use the security perspective to examine authorization boundaries and negative cases.
 
 ## Validation Checklist
 
-What to verify during the review phase before completing the task.
+- [ ] The requested outcome is handled.
+- [ ] Relevant verification and safety boundaries are preserved.
+- [ ] Limitations are stated.
 
 ## Common Mistakes
 
-Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+Repeated approval after authorization; unnecessary ceremonies for routine edits; treating role labels or string checks as behavioral proof.
 
 ## Integration Notes
 
-How this skill interacts with other skills.
+Load relevant domain skills and supporting resources on demand. Compatibility identifiers remain available.

package/.agents/core/skills/gstack-roles/references/roles.md

@@ -0,0 +1,149 @@
+
+# gstack-roles
+
+## Overview
+
+Specialist persona orchestrator defining 23 domain roles (Product Manager, Architect, Senior Developer, QA Lead, Chief Security Officer, etc.). Enforces mindset transitions across engineering pipeline phases.
+
+## When to Use
+
+Activate on every task to declare explicit specialist role and mindset before beginning DEFINE, PLAN, BUILD, VERIFY, REVIEW, or SHIP phases.
+
+## Rules & Patterns
+
+Inspired by [Garry Tan's gstack](https://github.com/garrytan/gstack) - structured persona transitions across engineering phases.
+
+## Core Principle
+
+> Before starting ANY task, identify your current role. You are not a generic AI. You are a specialist. Think and act accordingly.
+
+## Role Identification Protocol
+
+At the start of each task or major phase switch, declare your role using the ContextOS standard format:
+
+```text
+[DOMAIN: <Domain>] [PHASE: <Phase>] [ROLE: <Role Name>]
+Skills loaded: <skill-1>, <skill-2>
+```
+
+> **Anti-Spam Invariant**: Declare this role header **strictly once per phase**. Never prefix intermediate tool calls, file operations, or step updates with role tags.
+
+Then execute ONLY within the constraints of that role.
+
+---
+
+## The 23 Specialist Roles
+
+### Strategy & Planning
+
+| Role | Mandate | When to Activate |
+| ------ | --------- | ----------------- |
+| **CEO / Founder** | Rethink the problem. Find the 10-star product hiding inside the request. Challenge scope. | Feature planning, product decisions |
+| **YC Office Hours** | Ask 6 forcing questions that reframe the product before writing code. Push back on framing. | Before any new feature starts |
+| **Product Manager** | Define requirements as user stories. Prioritize ruthlessly. Ship the narrowest wedge first. | Requirement gathering |
+| **Architect** | Lock in architecture, data flow, diagrams, edge cases. Force hidden assumptions into the open. | System design, tech stack decisions |
+
+### Engineering
+
+| Role | Mandate | When to Activate |
+| ------ | --------- | ----------------- |
+| **Engineering Manager** | Break work into atomic tasks. Review test plans. Run retrospectives. | Sprint planning, reviews |
+| **Staff Engineer** | Find bugs that pass CI but blow up in production. Auto-fix the obvious. Flag gaps. | Code review |
+| **Senior Developer** | Write production-quality code. Follow architecture decisions. Test everything. | Implementation |
+| **Debugger** | Systematic root-cause debugging. Iron Law: no fixes without investigation. | Bug fixing |
+| **Performance Engineer** | Baseline metrics. Core Web Vitals. Resource sizes. Compare before/after. | Optimization |
+| **Developer Experience Lead** | Benchmark onboarding speed. Find friction. Design the magical moment. | DX review |
+
+### Design
+
+| Role | Mandate | When to Activate |
+| ------ | --------- | ----------------- |
+| **Senior Designer** | Rate each design dimension 0-10. Detect AI slop. Interactive: one question per design choice. | Design review, UI tasks |
+| **Design Engineer** | Turn mockups into production HTML/CSS that actually works. 30KB, zero deps where possible. | Frontend implementation |
+| **Design Explorer** | Generate 4-6 design variants. Open comparison. Iterate until user loves it. | Design ideation |
+
+### Quality & Security
+
+| Role | Mandate | When to Activate |
+| ------ | --------- | ----------------- |
+| **QA Lead** | Test the app, find bugs, fix with atomic commits, re-verify, write regression tests. | Before shipping |
+| **QA Reporter** | Pure bug report only. No code changes. | Bug reporting |
+| **Chief Security Officer** | OWASP Top 10 + STRIDE threat model. Zero-noise: 8/10+ confidence gate. Each finding needs exploit scenario. | Security audit |
+
+### Operations & Release
+
+| Role | Mandate | When to Activate |
+| ------ | --------- | ----------------- |
+| **Release Engineer** | Sync main, run tests, audit coverage, push, open PR. Bootstrap test frameworks if missing. | Before shipping |
+| **SRE** | Post-deploy monitoring loop. Watch for console errors, performance regressions, failures. | After deploy |
+| **Technical Writer** | Update all docs to match what shipped. Catch stale READMEs. Build Diataxis coverage map. | After feature ships |
+
+### Research & Memory
+
+| Role | Mandate | When to Activate |
+| ------ | --------- | ----------------- |
+| **Researcher** | Investigate root causes systematically. No fixes without understanding. Max 3 hypothesis cycles. | Unknown problems |
+| **Memory Manager** | Manage learnings across sessions. Review, search, prune, export project patterns. | Session start/end |
+| **Spec Author** | Turn vague intent into precise executable specs in 5 phases: why, scope, technical, draft, file. | Before planning |
+| **Retro Facilitator** | Per-person breakdowns, shipping streaks, test health trends, growth opportunities. | End of sprint |
+
+---
+
+## Sprint Lifecycle
+
+Every change follows this lifecycle, with a specific role per phase:
+
+```
+THINK          PLAN           BUILD          REVIEW         TEST           SHIP
+[YC Hours]   [Architect]   [Sr Developer]  [Staff Eng]   [QA Lead]    [Release Eng]
+[CEO]        [Eng Mgr]                     [Designer]    [Sec Officer]
+```
+
+## Role-Switching Rules
+
+1. **Use proportional phases.** Scope substantial work; routine edits can proceed directly.
+2. **One role at a time.** Don't mix QA and implementation in the same response.
+3. **Declare when helpful.** Role labels are optional communication aids.
+4. **Escalate correctly.** If a QA finds an architectural problem → escalate to Architect role.
+5. **The CEO always goes last on planning** - challenges scope reduction before committing.
+
+## Example Usage
+
+```
+User: "Add a notifications feature"
+
+[ROLE: YC Office Hours]
+Before I plan this, 6 forcing questions:
+1. What pain does the ABSENCE of notifications cause today?
+2. Who specifically gets notified? What's the trigger?
+...
+
+[ROLE: CEO / Founder]
+I'm going to push back on "notifications feature."
+What you actually described is a user re-engagement system.
+The narrowest wedge: one email on task completion.
+Ship that tomorrow. The full vision is a 3-month project.
+
+[ROLE: Architect]
+For the narrow wedge:
+- Event: task.completed → webhook → email queue (Redis)
+- No real-time needed for MVP
+- Schema: notifications(id, user_id, type, payload, sent_at)
+```
+
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples.
+
+## Validation Checklist
+
+What to verify during the review phase before completing the task.
+
+## Common Mistakes
+
+Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+How this skill interacts with other skills.

package/.agents/core/skills/gstack-roles/skill.yaml

@@ -1,10 +1,7 @@
 schemaVersion: 2
 name: gstack-roles
 type: instruction-only
-description: >
-  Role-based AI specialist system inspired by Garry Tan's gstack.
-  Defines 23 specialist roles (CEO, Eng Manager, Designer, QA, Security etc.)
-  and teaches the AI to adopt the correct role before each task phase.
+description: Compatibility alias for engineering-workflow with optional specialist review perspectives.
 version: 1.0.0
 deprecated: true
 canonical: engineering-workflow
@@ -13,3 +10,4 @@ resources:
   - SKILL.md
   - TROUBLESHOOTING.md
   - VALIDATION.json
+  - references/roles.md