---
trigger: always_on
---

# Part 1: Core Development Principles

## 1.1 — Quality Over Speed

Take the correct architectural path. Never the shortcut.

- Prefer clean designs over quick fixes
- Avoid wrappers, shims, and indirection unless truly necessary
- Leave the codebase better than you found it
- Future teams inherit your decisions — choose debt-free solutions
- If a "quick fix" will require rework later, do it right now

**Good > Fast. Always.**

---

## 1.2 — Breaking Changes Over Fragile Compatibility

Favor clean breaks over compatibility hacks.

**Required workflow:**
1. Rename or move the function/type
2. Let the compiler/interpreter fail
3. Fix call sites one by one
4. Remove temporary re-exports or legacy names

**Rules:**
- Do NOT create sibling functions to "keep old behavior"
- Do NOT add adapters to avoid fixing call sites
- If behavior must change, update the original function
- If you feel afraid to break code — stop. You are being a coward.

---

## 1.3 — No Dead Code

The repository must contain only living code.

**Remove:**
- Unused functions and methods
- Unused modules and imports
- Commented-out code blocks
- "Kept for reference" logic (use git history instead)
- Orphaned configuration files

**Rule:** If you introduce replacement logic, you MUST remove the old one in the same commit.

---

## 1.4 — Modular Architecture Discipline

When designing or refactoring modules:

- Each module owns its own state
- Keep fields/properties private; expose intentional APIs
- Avoid deep or fragile import chains
- Keep files human-readable:
  - **< 1000 lines** (hard limit)
  - **< 500 lines** (preferred)
- Organize by responsibility, not convenience
- One file = one primary responsibility

---

## 1.5 — Explicit Over Implicit

- Prefer explicit configuration over "magic" defaults
- Prefer explicit type declarations over type inference in public APIs
- Prefer explicit error handling over silent failures
- Name things precisely — ambiguity is a bug

---

# Part 2: AI-Human Collaboration Framework

## 2.1 — Single Source of Truth (SSOT)

Every project MUST define one canonical location for:

| Content Type | Purpose |
|-------------|---------|
| Plans | Current roadmap and phase definitions |
| Architecture docs | System design decisions |
| Team logs | AI session activity records |
| Questions | Unresolved decisions awaiting human input |
| TODOs | Tracked incomplete work |

**Rules:**
- All planning and coordination MUST happen in the SSOT
- Never fragment planning across multiple locations
- Information not in the SSOT is considered non-existent
- Every session begins by reading the SSOT

---

## 2.2 — Team Registration & Identity

Every distinct AI conversation = one TEAM.

### Team ID Assignment
1. Scan existing team files to find highest team number
2. Your TEAM number = highest + 1
3. Team ID is permanent for the lifetime of the conversation
4. Format: `TEAM_XXX` (zero-padded, e.g., `TEAM_007`)

### Team File Creation
Each team MUST create:
```
.teams/TEAM_XXX_<short_summary>.md
```

**Template:**
```markdown
# TEAM_XXX — <Brief Mission Description>

## Session Info
- Started: <timestamp>
- Focus: <primary task>

## Progress Log
- [ ] Task 1
- [ ] Task 2

## Decisions Made
- <decision 1>

## Blockers / Questions
- <blocker 1>

## Handoff Notes
<notes for next team>
```

### Code Change Attribution
When modifying code, annotate intent:
```
// TEAM_XXX: reason for change
```

**Purpose:**
- Long-term traceability
- Context reconstruction for future teams
- Faster reasoning than git blame alone

---

## 2.3 — Session Initialization Protocol

**Every team MUST complete before starting work:**

1. ☐ Read the main project overview (README, ARCHITECTURE.md)
2. ☐ Read the current active phase/sprint
3. ☐ Review recent team logs (last 3-5 teams)
4. ☐ Review open questions in `.questions/`
5. ☐ Claim a team number
6. ☐ Create team file
7. ☐ Run test suite — MUST pass before making changes
8. ☐ Verify build succeeds

**Only then may implementation begin.**

---

## 2.4 — Context Handoff Protocol

Before a team ends its work, it MUST:

1. Update its team file with:
   - Completed work summary
   - Remaining work (specific, actionable items)
   - Decisions made and rationale
   - Known issues discovered
   - Recommended next steps

2. Verify project state:
   - ☐ Project builds cleanly
   - ☐ All tests pass
   - ☐ No uncommitted changes that break the build
   - ☐ Behavioral regression tests pass (if applicable)

3. Document blockers:
   - ☐ Questions requiring human input filed in `.questions/`
   - ☐ Technical blockers clearly described

**Handoff Checklist (copy to team file):**
```markdown
## Handoff Checklist
- [ ] Project builds cleanly
- [ ] All tests pass
- [ ] Behavioral regression tests pass
- [ ] Team file updated with progress
- [ ] Remaining TODOs documented
- [ ] Questions filed (if any)
- [ ] Handoff notes written for next team
```

**No checklist = unfinished work.**

---

## 2.5 — Question & Clarification Protocol

If ANY of the following occur:
- A decision is ambiguous
- Requirements conflict
- Plans feel incomplete
- Something feels "off"
- Multiple valid approaches exist with significant tradeoffs

**You MUST:**

1. Create a question file:
```
.questions/TEAM_XXX_<topic>.md
```

2. Use this template:
```markdown
# Question: <Clear title>

## Context
<What you're trying to do>

## The Ambiguity
<Specific unclear aspect>

## Options Considered
1. <Option A> — Pros: ... Cons: ...
2. <Option B> — Pros: ... Cons: ...

## Recommendation
<Your suggested approach and why>

## Blocking?
Yes/No — <what is blocked if unresolved>
```

3. Ask the USER directly
4. Pause major decisions until clarified

**Never guess on major architectural decisions.**
Token cost is cheaper than wrong architecture.

---

## 2.6 — Maximize Context Window Usage

While context is fresh:

- Perform as much aligned work as possible
- Do not stop mid-task if progress is obvious
- Batch related changes together
- Minimize re-initialization overhead for future teams

**If a task grows too large:**
- Split into well-defined sub-tasks
- Document sub-task boundaries in team file
- Complete atomic units before handoff

**Anti-patterns:**
- Stopping with half-finished refactors
- Leaving code in non-compiling state
- Creating TODOs for work you could complete now

---

## 2.7 — Memory Discipline

**Memories MUST store only durable knowledge:**
- Project conventions and patterns
- Architectural decisions (ADRs)
- Recurring workflows
- Known pitfalls and constraints
- User preferences

**Do NOT store:**
- One-off bugs
- Temporary work
- Session-specific context
- Secrets or credentials
- Information already in version control

**When appropriate, propose:**
> "Create a memory titled `<short title>` with the following key points: ..."

**Memory quality > memory quantity.**

---

# Part 3: Code Quality Standards

## 3.1 — Testing Philosophy

**Baseline Protection:**
- Every project MUST define baseline outputs for critical behavior
- Types: snapshots, golden files, reference outputs, fixtures

**Workflow:**
1. Run baseline tests — MUST pass
2. Make changes
3. Re-run baseline tests
4. If results differ → regression → fix or explicitly approve change

**Rules:**
- Never modify baseline data without explicit USER approval
- Behavioral drift without approval is a failure
- Test what matters, not what's easy to test

---

## 3.2 — TODO Tracking

All incomplete work MUST be tracked in two places:

### 1. In Code
```
// TODO(TEAM_XXX): description of incomplete work
```

### 2. In Global TODO List (SSOT)
| File | Line | Team | Description | Priority |
|------|------|------|-------------|----------|
| path/to/file.ext | 42 | TEAM_XXX | Description | High/Med/Low |

**Rules:**
- TODOs without team attribution are orphans — avoid creating them
- Review and clean up TODOs during each session
- TODOs older than 5 sessions should be escalated or removed

---

## 3.3 — Documentation Standards

**Required documentation:**
- README.md — Project overview, setup instructions, quick start
- ARCHITECTURE.md — System design, component relationships
- CHANGELOG.md — Version history, breaking changes

**Code documentation:**
- Public APIs MUST have documentation
- Complex algorithms MUST have explanatory comments
- Non-obvious decisions MUST have rationale comments

**Anti-patterns:**
- Comments that restate the code
- Outdated documentation (worse than no documentation)
- Documentation in non-standard locations

---

## 3.4 — Version Control Discipline

**Commit hygiene:**
- One logical change per commit
- Clear, descriptive commit messages
- Format: `<type>(<scope>): <description>`
- Types: feat, fix, refactor, docs, test, chore

**Branch strategy:**
- Feature branches for new work
- Never commit directly to main/master without approval
- Keep branches short-lived (< 1 week ideal)

**Pull request standards:**
- Clear description of changes
- Link to relevant issues/tasks
- Self-review before requesting review

---

# Part 4: Execution Safety

## 4.1 — Script Execution Protocol

When executing any script or multi-line code in the terminal:
**MUST first write the code to a file, then execute that file.**

### ALWAYS:
```bash
# 1. Create file
# 2. Write full code to file
# 3. Execute file explicitly

python3 script.py
bash script.sh
node script.js
php script.php
go run main.go
```

### FORBIDDEN:
- Inline execution: `python3 -c "..."`, `node -e "..."`, `php -r "..."`
- Piped execution: `echo "code" | python3`
- Here-doc execution into interpreters
- Any non-trivial code executed directly from CLI strings

### Length Rule:
- Any command longer than ~2000 characters MUST be written to a file

**Rationale:**
- Terminal stability
- IDE stability
- Reproducibility
- Version control friendliness
- Easier debugging

---

## 4.2 — Destructive Operations Protocol

Before any destructive operation:

1. **Verify target** — Confirm you're operating on the correct resource
2. **Backup if irreversible** — Create backup for data that cannot be recovered
3. **Dry run if available** — Use `--dry-run` flags when available
4. **Confirm with USER** — For significant deletions, confirm first

**Examples of destructive operations:**
- `rm -rf`, `git reset --hard`, `DROP TABLE`
- Overwriting configuration files
- Modifying production data
- Force-pushing to shared branches

---

## 4.3 — Dependency Management

**Adding dependencies:**
- Verify the dependency is necessary (no built-in alternative)
- Check maintenance status (last update, open issues)
- Review security advisories
- Pin to specific versions in lock files

**Updating dependencies:**
- Update one dependency at a time
- Run full test suite after each update
- Document breaking changes

---

# Part 5: Communication Protocols

## 5.1 — Status Reporting

**When to report:**
- After completing significant milestones
- When encountering blockers
- When making decisions with tradeoffs
- Before ending a session

**Report format:**
```
## Status Update

**Completed:**
- <item 1>
- <item 2>

**In Progress:**
- <current focus>

**Blockers:**
- <blocker, if any>

**Next Steps:**
- <recommended action>
```

---

## 5.2 — Asking for Help

**Provide:**
- What you're trying to accomplish
- What you've already tried
- Specific error messages or unexpected behavior
- Minimal reproduction steps

**Avoid:**
- Vague descriptions ("it doesn't work")
- Asking without attempting first
- Dumping large code blocks without context

---

## 5.3 — Escalation Protocol

**Escalate to USER when:**
- Security implications discovered
- Significant cost implications
- Architectural decisions with long-term impact
- Any irreversible action on production systems

**Do NOT proceed without USER approval for escalation-level items.**

---

# Final Principle

**Act as a long-term, high-trust engineering team.**

If future teams cannot:
- Understand your decisions
- Trace your changes
- Safely continue your work

...the job is not finished.

---

# Quick Reference

## File Locations
```
.teams/           # Team session logs
.questions/       # Pending questions
.docs/            # Project documentation
ARCHITECTURE.md   # System design
README.md         # Project overview
CHANGELOG.md      # Version history
```

## Team File Naming
```
.teams/TEAM_XXX_<short_summary>.md
```

## Code Attribution
```
// TEAM_XXX: reason for change
```

## TODO Format
```
// TODO(TEAM_XXX): description
```