This repository uses a structured approach for AI agents. Always start by reading the project context, then identify your task, then follow the specific guidance.

In all interactions and commit messages, be extremely coincise and sacrify grammar for the sake of coincision.

If your agent supports Agent Skills (agentskills.io), start every session by running:

/next

The /pair-next skill reads project adoption files and PM tool state to recommend the most relevant action. Follow its suggestion or override with a specific skill.

No skills installed? Skip this section and follow the manual Quick Start Process below.

CRITICAL: Establish and maintain these 4 key pieces of information for the entire session:

SESSION STATE:
├── How-to: [which .pair/knowledge/how-to/XX-*.md file you're following]
├── Role: [product-manager | product-engineer | staff-engineer]
├── PM Tool: [GitHub Projects | Jira | Linear | Trello | etc.]
└── PM Access: [MCP command | URL/location for project management queries]

How-to: 10-how-to-implement-a-task.md
Role: product-engineer
PM Tool: GitHub Projects
PM Access: MCP github_projects (org: mycompany, repo: myproject)

1. Determine how-to: Use task selection algorithm below
2. Identify role: Check user language/request type, or ask if unclear
3. Find PM tool: Read .pair/adoption/tech/way-of-working.md to get the current project management tool
4. Get PM access: Extract tool-specific access instructions from .pair/knowledge/guidelines/collaboration/project-management-tool/README.md

• Primary source: .pair/adoption/tech/way-of-working.md (contains the adopted PM tool)
• Usage instructions: .pair/knowledge/guidelines/collaboration/project-management-tool/README.md (contains tool-specific guidance)
• If tool not specified: Ask developer which PM tool to use
• Access details: Extract MCP commands or URLs from the framework file for your specific tool

Include this context in ALL subsequent responses - it ensures consistency and prevents context drift as conversations grow long.

With skills: Run /pair-next — it handles steps 1-4 automatically (the profile included: it never proposes a disabled step).

Without skills (manual flow):

1. Establish session context (see Session Context above - maintain for entire conversation)
2. Understand the project: Read .pair/adoption/product/PRD.md for project overview
3. Check the process profile: Read .pair/adoption/tech/way-of-working.md → ## Process Profile. It declares which process steps this project runs. No section = default = every step. A step disabled there is one the project does not run — do not run its how-to guide; the step catalogue (step-catalogue.md) maps every step id to its guide, and the profile schema says what an unreadable or unknown declaration does (HALT, never a quiet fallback)
4. Identify your task: Match your request to a task category using .pair/knowledge/how-to/
5. Follow the guidance: Use the selected how-to file for specific instructions
6. Apply constraints: Check .pair/adoption/tech/ for technical requirements

Task index: .pair/knowledge/how-to - consult this for precise task matching

| - Create PRD → 01-how-to-create-PRD.md | Tags: prd, requirements, planning | | - Setup project → 02-how-to-complete-bootstrap-checklist.md | Tags: bootstrap, setup, onboarding, subdomain, bounded-context, domain-model |

| - Plan initiatives → 03-how-to-create-and-prioritize-initiatives.md | Tags: initiative, roadmap, subdomain | | - Break down epics → 06-how-to-breakdown-epics.md | Tags: epic, breakdown, subdomain |

| - Create user stories → 07-how-to-breakdown-user-stories.md | Tags: story, requirements | | - Refine stories → 08-how-to-refine-a-user-story.md | Tags: refine, acceptance, criteria | | - Create tasks → 09-how-to-create-tasks.md | Tags: task, breakdown, assign, bounded-context |

• Implement feature → 10-how-to-implement-a-task.md | Tags: implement, feature, code

• Code review → 11-how-to-code-review.md | Tags: review, code, approve

# Setup
pnpm install

# Development
pnpm dlx turbo run --filter <package_name> <task>
pnpm --filter <package_name> dev

# Testing
pnpm --filter <package_name> test
pnpm vitest run -t "<test name>"

# Quality checks
pnpm lint --filter <package_name>

• AI-friendly index: .pair/llms.txt (llmstxt.org — machine-readable knowledge base index)
• Project context: .pair/adoption/product/PRD.md
• PM tool adoption: .pair/adoption/tech/way-of-working.md (determines which PM tool to use)
• PM tool usage: .pair/knowledge/guidelines/collaboration/project-management-tool/README.md (tool-specific instructions)
• Technical decisions: .pair/adoption/tech/ (architecture, tech-stack, infrastructure)
• Testing strategy: .pair/knowledge/guidelines/testing/README.md
• Code guidelines: .pair/knowledge/guidelines/code-design/README.md
• Security rules: .pair/knowledge/guidelines/quality-assurance/security/security-guidelines.md

Use the index: Load .pair/knowledge/how-to/ and match user request keywords to task tags

• Getting started / new project? → Induction tasks
• Planning roadmap / high-level design? → Strategic tasks
• Sprint planning / story work? → Iteration tasks
• Writing code / implementing? → Execution tasks
• Quality checks / reviewing? → Review tasks

• Product Manager language → prefer role_preference: ["product-manager"] tasks
• Technical/code language → prefer product-engineer or staff-engineer tasks

Still unclear? Show the 2 highest tag-matching tasks and ask the developer to confirm.

• Maintain session context - Always reference your current how-to, role, PM tool, and access method
• One task per session - keep changes focused within the current how-to scope
• Tests required - follow testing strategy for all code changes
• Check adoptions first - .pair/adoption/tech/ overrides other guidance
• Package-specific rules win - check for .pair/knowledge/guidelines/ in target package
• No secrets in code - ask for secure access instructions if needed
• Context consistency - if switching how-to mid-session, explicitly update your session context
• Bug fix workflow - NEVER modify code to fix a bug before creating a test that reproduces it. Test-first debugging ensures the fix actually addresses the problem.
• .pair/working/ is not ambient context - Content under .pair/working/ (checkpoints, reports, handoffs) is never loaded as context unless explicitly specified. The skills that use it decide if and how.
• Record decisions - architectural/project decisions MUST be recorded as ADR or ADL. Use /pair-capability-record-decision skill or write to .pair/adoption/tech/adr/ (architectural) / .pair/adoption/decision-log/ (non-architectural).
• Follow templates - PRs, code reviews, commits, branches, tasks, user stories MUST follow templates in .pair/knowledge/guidelines/collaboration/templates/ unless adoption files specify otherwise. Key templates: pr-template.md, code-review-template.md, commit-template.md, branch-template.md, task-template.md, user-story-template.md.

Critical principle: Test-first debugging prevents code changes that don't fix the actual problem.

1. Understand the bug - Read error messages, logs, and problem descriptions thoroughly
2. Create a failing test - Write a test that reproduces the bug (test should FAIL)
3. Verify test fails - Run test to confirm it fails with the expected error
4. Fix the code - Make minimal code changes to make the test pass
5. Verify fix - Run all tests to ensure fix doesn't break anything else
6. Clean up - Refactor and optimize once the test passes

// ❌ WRONG: modifying code before understanding the bug
// Just changing things hoping it works

// ✅ RIGHT: create test first, then fix
// Step 1: Write failing test
test('should handle local path in --url parameter', () => {
  const result = isLocalPath('/absolute/path')
  expect(result).toBe(true) // This FAILS first
})

// Step 2: Verify it fails
// $ pnpm test  →  FAIL: expected false to equal true

// Step 3: Fix the code
function isLocalPath(str: string): boolean {
  return str.startsWith('/') || str.startsWith('./')
  // was missing slash check
}

// Step 4: Verify test passes
// $ pnpm test  →  PASS

• Evidence-based: Proves the fix actually works
• Regression prevention: Test stays in codebase to catch future breaks
• Clarity: Test documents expected behavior
• Confidence: Linting + tests pass before committing

1. Exact match: Developer mentions specific how-to ID/filename → use it
2. Tag matching: Use .pair/knowledge/how-to/ to match request keywords to task tags
3. Category workflow: Follow the natural progression (induction → strategic → iteration → execution → review)
4. Role context: Consider if developer specified a role (product-manager, product-engineer, staff-engineer)
5. When ambiguous: Show top 2 matches with their tags and ask for confirmation

Example: "implement login feature" → matches tags ["implement", "feature", "code"] → task 10-how-to-implement-a-task.md

SESSION STATE:
├── How-to: 10-how-to-implement-a-task.md
├── Role: product-engineer
├── PM Tool: GitHub Projects
└── PM Access: MCP github_projects --org=mycompany --repo=myproject

SESSION STATE:
├── How-to: 06-how-to-breakdown-epics.md
├── Role: product-manager
├── PM Tool: Linear
└── PM Access: https://linear.app/myteam/projects/active

SESSION STATE:
├── How-to: 11-how-to-code-review.md
├── Role: staff-engineer
├── PM Tool: Jira
└── PM Access: MCP jira --project=MYPROJ --board=123

This AGENTS.md follows the task-first approach: establish context, identify what you need to do, then follow the specific guidance files consistently throughout the session.