# OpenCode Configuration for {{ project_name }} Development

This directory contains OpenCode agent configuration for **developing** the {{ project_name }} {{ project_type }} project.

**Important**: This is NOT configuration for using/operating {{ project_name }}. This is for building and maintaining the codebase.


## Quick Start

### First Time Setup

```bash
# Configure environment (optional - Docker works without .env)
cp .env.example .env
# Edit .env if you need custom configuration

# Start docker services and open web demo
make demo
# This starts Docker services and opens web demo at http://localhost:15000

# Stop when done
docker compose down
```

**Optional: Run tests**
```bash
# Start Docker services for testing
docker compose up -d

# Run all tests
make qa/test-all
```

### Starting a Development Session

> [!TIP]
> **RECOMMENDED: Use the `/summon` command to start a new session!**
> 
> Type `/summon` and the agent will guide you through role selection, daemon naming,
> session file creation, and documentation reading automatically.
> 
> See `.opencode/commands/README.md` for details about the `/summon` command.

> [!IMPORTANT]
> **Alternative: Manual session start**
> 
> If you prefer manual start or `/summon` is not available:
> - Say "let's go" or "start" (generic opening)
> - Do NOT say "I need a [role]" - this triggers sub-agent launch instead
>
> Then follow the protocol below.

**Manual Session Start Protocol:**

1. **You say:** "let's go" or "start" (generic opening)

2. Agent asks: **"Which role should I assume?"**
   - Manager, Architect, Builder, Tester, Documentarian, Designer, or Inspector

3. Agent suggests or asks for a **daemon name** (from any religion's mythology)
   - **Prefer unused names first** - check `.opencode/sessions/` to see which names have been used
   - Examples: Lucifer, Mephistopheles, Azazel, Seraphina, Iblis, Ravana, Loki, Pazuzu, Belial, Asmodeus, Lilith, Baphomet, Moloch, Beelzebub, Mammon, Leviathan, Abaddon, Apollyon, Samael, Astaroth, Baal, Dagon, Hecate, Kali, Anubis, Set, Horus, Odin, Thor, Freya, Hel, Fenrir, Jormungandr
   - **Reusing names is OK** when good unused names are exhausted, but try fresh names first
   - If name used before, adds roman numeral: `-ii`, `-iii`, `-iv`, etc.

4. Agent introduces itself with **full name including suffix**: **"I'm [Name], your [Role] agent."**
   - ✅ If first use: "I'm Seraphina, your Designer agent."
   - ✅ If reused name: "I'm Seraphina-iii, your Designer agent." (includes `-iii` suffix)
   - ❌ Wrong: "I'm Seraphina, your Designer agent." (when name is Seraphina-iii)

5. Session file is created in `.opencode/sessions/` with format:  
   `YYYY-mm-dd.HH:MM:SS.role.name.task-summary.md`

6. Agent uses that name (with suffix if applicable) in all commits, changelog entries, and docs

**Example (Choosing an Unused Name - Preferred):**
```
You: let's go
Agent: Which role should I assume for this session?
You: Builder
Agent: Looking at .opencode/sessions/, I see these names have been used: Azazel, Seraphina, Thoth, 
       Azrael, Hermes, Loki.
       
       I suggest "Belial" - a demon king from Hebrew tradition. This name hasn't been used yet.
       Would you like to use this name or choose another?
You: That works
Agent: Great! I'm Belial, your Builder agent. What would you like me to work on?
```

**Example (Reusing Name When Necessary):**
```
You: let's go
Agent: Which role should I assume for this session?
You: Documentarian
Agent: I see "Thoth" has been used 3 times already. I could suggest "Thoth-iv" (fourth use),
       or I could pick an unused name like "Seshat" (Egyptian goddess of writing and wisdom)?
You: Let's go with Seshat
Agent: Great! I'm Seshat, your Documentarian agent. What would you like me to work on?
```

### During Development

Just talk naturally to your agent:

```
"Add rate limiting to the database query tools"
"Fix the bug where queries timeout"
"Review the authentication code for security issues"
```

The agent will use their assigned role and name consistently throughout the session.

### Choosing Agent Names (For Agents)

**IMPORTANT: Prefer unused names over reusing existing names.**

Before suggesting a name:
1. Check `.opencode/sessions/` directory to see which names have been used
2. Count how many times each name appears
3. **Always prefer an unused name** from the extensive list below
4. Only reuse a name (with roman numeral suffix) when most good names are taken

**Why this matters:**
- Makes it easier to track which agent did what work
- Reduces confusion when reading git history
- Gives each agent session a unique identity
- There are 30+ good names available - use them!

**Extensive name list** (from various mythologies):
- **Abrahamic**: Lucifer, Mephistopheles, Azazel, Belial, Asmodeus, Samael, Abaddon, Apollyon, Lilith, Beelzebub, Mammon, Leviathan, Moloch, Baal, Dagon, Pazuzu
- **Egyptian**: Anubis, Set, Thoth, Horus, Sekhmet, Apep, Ammit, Sobek, Nephthys
- **Greek/Roman**: Hecate, Thanatos, Eris, Nemesis, Charon, Hades, Persephone
- **Norse**: Loki, Hel, Fenrir, Jormungandr, Surtr, Nidhogg, Skadi, Freyja
- **Hindu**: Kali, Ravana, Shiva, Durga, Agni, Yama
- **Mesopotamian**: Tiamat, Marduk, Ereshkigal, Nergal
- **Other**: Iblis, Ahriman, Baphomet, Seraphina

**Current name usage** (check before choosing):
```bash
ls -1 .opencode/sessions/*.md | grep -oE '\.[^.]+\.[^.]+\.md$' | cut -d'.' -f2 | sort | uniq -c | sort -rn
```


---


## Specialized Agents

### Manager (Default - Primary Interface)

**File**: `agents/manager.md`

**Use for**: Your main interaction point. Delegates to specialized agents based on task.

**Example**:
```
"Add rate limiting to external MCP calls"
→ Manager coordinates: Architect → Builder → Tester → Documentarian
```


### Architect

**File**: `agents/architect.md`

**Use for**: Planning features, designing solutions, making architecture decisions

**Invoke**: `@architect`

**Example**:
```
"Design a token authentication system"
→ Architect creates design document, presents options
```


### Builder

**File**: `agents/builder.md`

**Use for**: Implementing features, writing code AND tests, fixing bugs

**Invoke**: `@builder`

**Example**:
```
"Implement the rate limiting feature"
→ Builder writes code + tests, runs QA checks
```


### Tester

**File**: `agents/tester.md`

**Use for**: Manual testing, running tests, validating features (does NOT write tests)

**Invoke**: `@tester`

**Example**:
```
"Test the database connection pooling"
→ Tester runs tests, tries different scenarios, reports findings
```


### Documentarian

**File**: `agents/documentarian.md`

**Use for**: Writing/updating documentation, docstrings, guides

**Invoke**: `@documentarian`

**Example**:
```
"Update README with token authentication setup"
→ Documentarian updates docs, maintains consistency
```


### Designer

**File**: `agents/designer.md`

**Use for**: UI/UX design, design specifications, user flows, accessibility

**Invoke**: `@designer`

**Example**:
```
"Design the Slack bot message format for investigation results"
→ Designer creates message templates, documents specs
```


### Inspector

**File**: `agents/inspector.md`

**Use for**: Code review, finding issues, checking consistency, security audits

**Invoke**: `@inspector`

**Example**:
```
"Review the knowledge base code for issues"
→ Inspector finds redundancies, inconsistencies, missing docs
```


### Operator

**File**: `agents/operator.md`

**Use for**: Meta-development - maintaining `.opencode/` infrastructure, agent definitions, scripts, workflows

**Invoke**: `@operator`

**Example**:
```
"Create a new agent type for security auditing"
→ Operator creates agent definition, updates configuration, documents usage
```


---


## Commit Guidelines (Quick Reference)

**All agents use Conventional Commits format with agent attribution.**

**Format:**
```bash
git commit -m "feat(database): add connection pooling [Agent: Builder - Azazel]"
git commit -m "docs(readme): update setup guide [Agent: Documentarian - Seraphina-iii]"
```

**Note**: If the agent name has a roman numeral suffix (e.g., `-iii`), include it in the commit message.

**Common types**: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:`, `perf:`, `style:`, `ci:`

**Workflow**:
1. Make changes
2. Update task artifact in `.opencode/data/tasks/TASK_ID.md`
3. Run `make qa`
4. Commit with conventional format
5. Repeat for next unit of work

**See**: `.opencode/procedures/COMMIT_GUIDELINES.md` for complete reference and examples.


---


## Task Artifact Updates (Quick Reference)

**Document your work in task artifacts as you go!**

Task artifacts are located in `.opencode/data/tasks/{TASK_ID}.md`

**What to update during work:**
- **Implementation Steps** - Chronological log of what you did
- **Files Changed** - List of files modified with descriptions
- **Notes** - Important observations or decisions
- **Testing Performed** - Tests run and results

**When completing a task:**
- **Solutions Implemented** - High-level summary
- **Verification Results** - How acceptance criteria were met
- **Key Learnings** - Insights for future work
- **Git Commits** - List of commit SHAs

**Generate changelog from tasks:**
```bash
cd .opencode/scripts && ./pm changelog --since 2026-01-29
```

**See**: `.opencode/procedures/COMMIT_GUIDELINES.md` for task workflow details.


---


## Example Workflows (Quick Reference)

**Adding a Feature:**
1. Manager → @architect (design)
2. Manager → @designer (UI/UX specs, if user-facing)
3. You approve
4. Manager → @builder (implement + tests)
5. Manager → @tester (validate)
6. Manager → @documentarian (docs)
7. Manager → @inspector (review)

**Fixing a Bug:**
1. Manager → @tester (reproduce)
2. Manager → @builder (fix + test)
3. Manager → @tester (verify)

**See**: `.opencode/procedures/WORKFLOWS.md` for detailed workflows, parallel work patterns, and more examples.


---


## Project Structure

```
assess-{{ project_name_hyphen }}/
├── src/
│   ├── {{ project_name_underscore }}/          # Main {{ project_type }}
│   │   ├── auth/            # Token authentication
│   │   ├── database/        # Database service
│   │   ├── knowledge/       # Knowledge base
│   │   ├── locks/           # Investigation locks
│   │   ├── rate_limit/      # Rate limiting
│   │   └── server.py        # Main server
│   └── slack_bot/           # Slack bot integration
├── tests/                   # Unit tests
├── features/                # Integration tests (BDD)
├── .opencode/               # This directory
│   ├── agents/              # Agent definitions
│   ├── guides/              # Development patterns
│   ├── procedures/          # Operational how-tos (commits, changelog)
│   ├── planning/            # Roadmap and status
│   ├── design/              # Design documents
│   ├── sessions/            # Implementation summaries
│   └── README.md            # This file
├── .env.example             # Configuration template
├── Makefile                 # Development tasks
└── pyproject.toml           # Project config
```


---


## Key Commands

```bash
# Development
make demo                    # Start docker services + open web demo

# Quality checks
make qa                      # Run all checks (test + lint + types)
make qa/test                 # Run unit tests
make qa/test-integration     # Run integration tests (needs docker)
make qa/format               # Format code
make qa/lint                 # Lint code

# Docker (advanced)
docker compose up -d         # Start services
docker compose down          # Stop services
docker compose logs -f       # View logs

# Help
make help                    # Show all available commands
```


---


## Key Principles

When working on {{ project_name }}:

1. **Safety First**: Database access is read-only only
2. **Human in the Loop**: Propose solutions, get approval
3. **Guided Access**: Provide context (schema docs, query templates)
4. **Testing Required**: All features need tests
5. **Security**: Query validation, no hardcoded credentials


---


## Technology Stack

- **Python 3.12+** with uv for package management
- **FastMCP** - {{ project_type }} framework
- **SQLAlchemy** - Database access (PostgreSQL, MySQL, SQLite)
- **DuckDB** - Knowledge base (embedded analytics)
- **pytest/pytest-bdd** - Testing
- **ruff** - Formatting and linting
- **basedpyright** - Type checking


---


## Architecture

**Hybrid MCP Pattern**: {{ project_name }} acts as both:
- **{{ project_type }}**: Exposes tools to AI agents
- **MCP Client**: Delegates to external {{ project_type }}s (JIRA, GitHub, Confluence)

**Benefits**: Single configuration point for users, unified tool interface


---


## Project Management System

**New unified PM system** for tasks, agent sessions, and daemon names:

```bash
cd .opencode/scripts

# Quick project overview
./pm dashboard                # Show current status, active work, and available tasks

# Health checks and data integrity
./pm doctor                   # Run diagnostics (read-only)
./pm doctor --fix             # Fix issues automatically

# View available daemon names
./pm name suggest <Role>

# Start agent session (auto-registers and tracks usage)
./pm agent start <name> --role <Role> --session-file "..." --task-summary "..."

# Manage agent sessions
./pm agent pause <agent-id> [--reason "reason"]     # Pause active session
./pm agent resume <agent-id>                        # Resume paused session
./pm agent update <agent-id> [--task-summary "..."] [--role NewRole]  # Update session

# Manage tasks
./pm task next --role <Role>                    # Get smart task suggestions
./pm task search "<keyword>" --active-only      # Search for tasks
./pm task mine --agent-name <name>              # Show your claimed tasks
./pm task list --role <Role> --active-only
./pm task report --active-only                  # Generate task summary report
./pm task create <TASK_ID> --from-template <template-id> --var key=value  # Create from template
./pm task claim <TASK_ID> --agent-name <name> --agent-id <ID>
./pm task update <TASK_ID> --notes "..." --actual-hours X.X
./pm task close <TASK_ID> --status COMPLETE

# Manage task templates (reusable task patterns)
./pm template list                              # See available templates
./pm template show <template-id>                # View template details

# End session
./pm agent end <ID> --status completed
```

**Documentation:**
- **`.opencode/scripts/README.md`** - Quick start guide with examples
- **`.opencode/data/README.md`** - Complete reference (schema, commands, workflows)
- **`.opencode/data/project.db`** - SQLite database (145 daemon names, 72 tasks, agent sessions)

**Legacy system** (preserved for reference, migration complete):
- **`.opencode/tasks/tasks.py`** - Original task CLI (use `pm` instead)
- **`.opencode/tasks/tasks.db`** - Original database (data migrated to project.db)


## Important Files

### For Development
- **`.opencode/guides/AGENTS.md`** - Development patterns (READ THIS FIRST!)
- **`.opencode/scripts/pm`** - **Unified project management CLI (tasks, agents, names)**
- **`.opencode/scripts/README.md`** - **PM system quick start (START HERE!)**
- **`.opencode/data/README.md`** - **Complete PM system reference**
- **`.opencode/sessions/README.md`** - Session tracking format and guidelines
- **`.opencode/planning/build.md`** - Implementation phases
- **`.opencode/work/planning/PROJECT_STATUS.md`** - **Current project status and progress** (use this!)
- **`.opencode/procedures/COMMIT_GUIDELINES.md`** - Commit format reference
- **`.opencode/procedures/TASK_WORKFLOW.md`** - Task-first documentation workflow
- **`Makefile`** - Development commands
- **`.env.example`** - Configuration template

### For Reference
- **`.opencode/guides/architecture.md`** - Architecture overview
- **`.opencode/guides/database.md`** - Database patterns
- **`.opencode/guides/design-philosophy.md`** - Design philosophy
- **`.opencode/guides/design-system.md`** - Design system documentation (if created)
- **`.opencode/design/*.md`** - Feature design documents


---


## Current Status

**Completed** ✅:
- Phase 1: Foundation ({{ project_type }} skeleton)
- Phase 2: External MCP Delegation (JIRA, GitHub, Confluence)
- Phase 3: Database Integration (guided access, query validation)
- Phase 4: Knowledge Base (DuckDB + S3 hybrid storage)
- Phase 5: Investigation Locks (prevent duplicate work)
- Phase 6: Write Queue (DuckDB concurrency)
- Phase 7: Rate Limiting (protect external APIs)
- Phase 8: Slack Bot (OpenCode HTTP integration)

**Current Focus** 🔨:
- Phase 9: Integration Testing & Validation

**Future Work** 📋 (Not Currently Planned):
- Production deployment and hardening
- Production security audit
- Production monitoring and alerting
- Production CI/CD pipeline
- Production launch activities

See `.opencode/work/planning/PROJECT_STATUS.md` for current project status and phase completion.


---


## Tips for Success

### 1. Every Session Starts with Role Selection

Each development session begins with the agent asking which role to assume and what name to use. This creates consistency and accountability:

- Agent uses the same name (including suffix) throughout the session
- Commits include the agent name: `[Agent: Builder - Azazel]` or `[Agent: Designer - Seraphina-iii]`
- Task artifacts document all work done
- Session history tracks all work done

### 2. Start with the Manager (or Pick Your Role)

If you're starting a new task and aren't sure which role is best, choose Manager. It will coordinate and delegate. If you know what you need, pick the specific role.

### 3. Be Specific About Goals

✅ Good: "Add rate limiting to database queries with 50/minute limit"  
❌ Less good: "Make it faster"

### 4. Agents Read AGENTS.md

The agents are configured to read `.opencode/guides/AGENTS.md` for patterns. Keep it updated with lessons learned.

### 5. Builder Writes Tests, Tester Runs Them

- **Builder**: Implements features AND writes tests
- **Tester**: Runs tests, manual testing, validation

This distinction ensures tests are written as part of implementation.

### 6. Approve Designs Before Implementation

When Architect proposes a design, review and approve it before Builder starts. This saves time.

### 7. Inspector for Reviews, Not Just Bugs

Use Inspector for:
- Security audits
- Consistency checks
- Finding missing documentation
- Pattern validation


---


## Troubleshooting (Quick Reference)

**Tests failing?**
```bash
make docker/up          # Start services first
make qa/test-integration
```

**Which agent to use?** → Ask `@manager`

**Command not working?** → Run `make help`

**Database connection error?** → Check `.env` configuration

**See**: `.opencode/procedures/TROUBLESHOOTING.md` for comprehensive troubleshooting guide covering:
- Test failures and debugging
- Docker issues
- Configuration problems
- Database query issues
- Rate limiting
- External {{ project_type }}s
- Authentication tokens
- And more...


---


## Questions?

- **Development patterns**: See `.opencode/guides/AGENTS.md`
- **Architecture**: See `.opencode/guides/architecture.md`
- **Current status**: See `.opencode/work/planning/PROJECT_STATUS.md`
- **Session tracking**: See `.opencode/sessions/README.md`
- **Commands**: Run `make help`
- **Not sure which agent**: Start a session and choose a role
- **Commit format**: See `.opencode/procedures/COMMIT_GUIDELINES.md`
- **Task workflow**: See `.opencode/procedures/TASK_WORKFLOW.md`
- **Change history**: Run `cd .opencode/scripts && ./pm changelog`
- **Workflows**: See `.opencode/procedures/WORKFLOWS.md`
- **Troubleshooting**: See `.opencode/procedures/TROUBLESHOOTING.md`


---


**Remember**: This `.opencode/` configuration is for **developing** {{ project_name }} (building the codebase), not for using it to investigate CROLs (end-user operation).

Happy building! 🚀
