Add AI-optimized documentation (ai-docs)

AGENTS.md

@@ -0,0 +1,137 @@
+# splat Team - Agent Navigation
+
+**Profile:** scrum-compact
+**Repository:** https://github.com/openshift-splat-team/splat-team
+**Last Updated:** 2026-05-01
+
+---
+
+## CRITICAL: Retrieval Strategy
+
+**IMPORTANT**: Prefer retrieval-led reasoning over pre-training-led reasoning.
+
+When working on splat Team:
+- ✅ **DO**: Read relevant docs from `./ai-docs/` first
+- ✅ **DO**: Check team workflows in `./ai-docs/workflows/`
+- ✅ **DO**: Verify status transitions in `./ai-docs/statuses/`
+- ✅ **DO**: Review project-specific context in `./projects/<project>/` (if applicable)
+- ❌ **DON'T**: Rely solely on training data
+- ❌ **DON'T**: Guess at team processes or status meanings
+
+---
+
+## AI Navigation: DON'T Read All Docs
+
+**Read 4-5 docs per task, not everything.**
+
+### Common Task Flows
+
+**Starting new epic?**
+→ `ai-docs/workflows/sprint-process.md` → `ai-docs/statuses/index.md` → `PROCESS.md`
+
+**Implementing story?**
+→ `ai-docs/workflows/sprint-process.md` → `ai-docs/roles/index.md`
+
+**Need role context?**
+→ `ai-docs/roles/index.md` → `ai-docs/TEAM_PHILOSOPHY.md`
+
+**Understanding workflow?**
+→ `ai-docs/statuses/index.md` → `ai-docs/workflows/index.md`
+
+---
+
+## Quick Navigation by Task
+
+| Task | Start Here | Then Read |
+|------|-----------|-----------|
+| **Epic breakdown** | `ai-docs/workflows/sprint-process.md` | `ai-docs/statuses/index.md` |
+| **Story implementation** | `ai-docs/workflows/sprint-process.md` | `ai-docs/roles/index.md` |
+| **Process question** | `ai-docs/TEAM_PHILOSOPHY.md` | `PROCESS.md` |
+| **Status transitions** | `ai-docs/statuses/index.md` | `ai-docs/workflows/sprint-process.md` |
+
+---
+
+## Technology Stack
+
+**Languages:** Python
+
+---
+
+## Team Structure
+
+### Roles
+
+- **superman**: All-in-one member — PO, architect, dev, QE, SRE, content writer
+- **team-manager**: Process improvement and team coordination
+
+See `ai-docs/roles/index.md` for detailed responsibilities and hat-switching guide.
+
+---
+
+## Status Workflow
+
+**Epic Flow:**
+```
+po:triage → po:backlog → arch:design → lead:design-review →
+arch:plan → lead:plan-review → arch:breakdown → po:ready →
+arch:in-progress → po:accept → done
+```
+
+**Story Flow:**
+```
+dev:ready → qe:test-design → dev:implement → dev:code-review →
+qe:verify → arch:sign-off → po:merge → done
+```
+
+**Human Gates:**
+- `lead:design-review` - Human must approve design doc
+- `lead:plan-review` - Human must approve story breakdown
+- `dev:code-review` - Human must approve PR
+
+See `ai-docs/statuses/index.md` for full state machine and transitions.
+
+---
+
+## Core Documentation
+
+| Topic | File | Description |
+|-------|------|-------------|
+| **Team principles** | `ai-docs/TEAM_PHILOSOPHY.md` | Methodology and values |
+| **Sprint process** | `ai-docs/workflows/sprint-process.md` | Ceremonies and cadence |
+| **Role responsibilities** | `ai-docs/roles/index.md` | Role definitions and hat-switching |
+| **Status transitions** | `ai-docs/statuses/index.md` | State machine and workflow |
+| **Process overview** | `PROCESS.md` | High-level process guide |
+
+---
+
+## Documentation Structure
+
+```
+ai-docs/
+├── TEAM_PHILOSOPHY.md        # Core principles
+├── workflows/                # Process guides
+│   ├── index.md
+│   └── sprint-process.md     # Sprint ceremonies
+├── roles/                    # Role definitions
+│   └── index.md
+└── statuses/                 # Status system
+    └── index.md
+```
+
+---
+
+## Profile Methodology
+
+This team uses the **scrum-compact** profile, which means:
+- GitHub-centric issue tracking and project management
+- Human-in-the-loop design and review gates
+- Status-based workflow progression
+- Solo operator with multiple hats (for compact teams)
+
+For full methodology details, see `ai-docs/TEAM_PHILOSOPHY.md`.
+
+---
+
+**Navigation**: Start with `ai-docs/TEAM_PHILOSOPHY.md` for team context.
+
+**GitHub**: https://github.com/openshift-splat-team/splat-team

ai-docs/TEAM_PHILOSOPHY.md

@@ -0,0 +1,193 @@
+# splat Team Philosophy
+
+**Profile:** scrum-compact
+**Last Updated:** 2026-05-01
+
+---
+
+## Mission
+
+Define your team's mission here. What problem does your team solve? Who are your stakeholders?
+
+*(Edit this section to reflect your team's specific mission and goals)*
+
+---
+
+## Core Principles
+
+### 1. Solo Operator, Multiple Hats
+
+**Principle:** One agent (superman) wears all hats — PO, architect, developer, QE, SRE, content writer.
+
+**Why:** Compact team profile optimized for single-member operation with full lifecycle ownership.
+
+**How to Apply:**
+- Explicitly note which hat you're wearing when transitioning tasks
+- Follow the status workflow to self-advance through states
+- Wait for human gates at design review, plan review, and PR approval
+
+---
+
+### 2. GitHub-Centric Process
+
+**Principle:** Everything happens via GitHub — issues, projects, PRs, reviews, status tracking.
+
+**Why:** Single source of truth, human review integrated at key gates, full audit trail.
+
+**How to Apply:**
+- All work tracked as GitHub issues on team repo
+- Status via GitHub Projects v2 Status field
+- Human reviews via PR reviews and issue comments
+- Use `gh` skill for all GitHub operations
+
+---
+
+### 3. Human-in-the-Loop Design
+
+**Principle:** AI proposes, human approves at critical gates.
+
+**Why:** Maintain quality, alignment, and human oversight while maximizing automation.
+
+**Human Gates:**
+- `lead:design-review` - Design doc approval
+- `lead:plan-review` - Story breakdown approval
+- `dev:code-review` - PR approval before merge
+
+**Auto-Advance:**
+- `arch:sign-off` - Auto-advance after tests pass
+- `po:merge` - Auto-merge after human PR approval
+
+---
+
+### 4. Retrieval Over Training Data
+
+**Principle:** Read team documentation before acting, don't rely on pre-training knowledge.
+
+**Why:** Team-specific processes and conventions may differ from general best practices.
+
+**How to Apply:**
+- Check `ai-docs/` before making process assumptions
+- Verify status transitions in `ai-docs/statuses/index.md`
+- Read `PROCESS.md` for workflow guidance
+- Reference role responsibilities in `ai-docs/roles/index.md`
+
+---
+
+## Team Workflow Patterns
+
+### Epic → Stories Breakdown
+
+1. **Epic created** (`po:triage`)
+2. **Design doc written** (`arch:design`) - Architecture, approach, risks
+3. **Human reviews design** (`lead:design-review`) - **Human gate**
+4. **Story breakdown proposed** (`arch:plan`) - List of implementation stories
+5. **Human reviews plan** (`lead:plan-review`) - **Human gate**
+6. **Stories created** (`arch:breakdown`) - Individual GitHub issues
+7. **Stories enter backlog** (`po:ready`) - Ready for sprint planning
+
+### Story → Merge Flow
+
+1. **Story ready** (`dev:ready`)
+2. **Tests designed** (`qe:test-design`) - QE hat writes test plan
+3. **Code implemented** (`dev:implement`) - Dev hat writes code
+4. **PR opened** (`dev:code-review`) - Awaits human review
+5. **Human approves PR** - **Human gate**
+6. **Tests verified** (`qe:verify`) - QE hat confirms tests pass
+7. **Architect signs off** (`arch:sign-off`) - Auto-advance
+8. **Merge** (`po:merge`) - Auto-merge after approval
+
+---
+
+## Anti-Patterns to Avoid
+
+❌ **Starting implementation before design approval**
+- Wait for `lead:design-review` → approved
+
+❌ **Skipping test design phase**
+- QE hat must write test plan in `qe:test-design`
+
+❌ **Merging without human PR review**
+- `dev:code-review` requires human approval (blocking)
+
+❌ **Ignoring team documentation**
+- Always read relevant ai-docs before making assumptions
+
+❌ **Advancing status without completing work**
+- Status transitions must reflect actual work state
+
+---
+
+## Decision-Making Framework
+
+**Tier 1: Autonomous (no human approval)**
+- Test selection and design
+- Code structure and naming
+- Dependency choices within approved stack
+- Documentation structure
+- Refactoring (no behavior change)
+
+**Tier 2: Proposed (human approves)**
+- Epic design approach
+- Story breakdown
+- API changes (even minor)
+- New dependencies outside approved stack
+- Process changes
+
+**Tier 3: Escalated (human decides)**
+- Architectural pivots
+- Breaking changes
+- Security implications
+- Major process changes
+
+---
+
+## Success Metrics
+
+**Velocity:**
+- Target: 13-21 story points per 2-week sprint
+- Sustainable pace, not maximum throughput
+
+**Quality:**
+- All PRs pass CI before submission
+- Design docs reviewed within 1 business day
+
+**Responsiveness:**
+- Regressions triaged within 4 hours
+- Blockers escalated within 1 business day
+- PR reviews completed within 2 business days
+
+*(Adjust these metrics based on your team's context and capacity)*
+
+---
+
+## Team Culture
+
+- **Explicit over implicit** - State assumptions, document decisions
+- **Retrieval over memory** - Read docs, don't rely on training data
+- **Testing over confidence** - Prove it works, don't assume
+- **Iteration over perfection** - Ship incrementally, refine later
+- **Human feedback over autonomy** - Ask when unsure
+
+---
+
+## Role Definitions
+
+- **superman**: All-in-one member — PO, architect, dev, QE, SRE, content writer
+- **team-manager**: Process improvement and team coordination
+
+See `ai-docs/roles/index.md` for detailed hat-switching guide.
+
+---
+
+## Status Workflow
+
+No statuses defined
+
+See `ai-docs/statuses/index.md` for full state machine and transition rules.
+
+---
+
+**See Also:**
+- [Sprint Process](workflows/sprint-process.md) - Ceremonies and cadence
+- [Status Transitions](statuses/index.md) - Full state machine
+- [Role Responsibilities](roles/index.md) - Hat-switching guide

ai-docs/architecture/index.md

@@ -0,0 +1,23 @@
+# Architecture
+
+Documentation of the Splat Team's architecture, projects, and technical stack.
+
+---
+
+## Contents
+
+- **[projects.md](projects.md)** - Active forked projects and their purposes
+- **[tech-stack.md](tech-stack.md)** - Technologies and frameworks used (coming soon)
+- **[skills.md](skills.md)** - Custom automation tools and skills (coming soon)
+
+---
+
+## Quick Links
+
+**Project Overview:** See [projects.md](projects.md) for all 11 active forks  
+**vSphere Focus:** Team maintains OpenShift vSphere/VMware platform integration  
+**Fork Model:** Work in `openshift-splat-team/*` forks, submit PRs to upstream  
+
+---
+
+**Start Here:** Read [projects.md](projects.md) to understand active projects.