# Contributing to trekplan

This is a solo project. Issues are welcome. PRs may be considered but are not expected.

## Reporting bugs

Open an issue with:
- Plugin version (from `.claude-plugin/plugin.json`)
- Claude Code version (`claude --version`)
- What you did, what you expected, what happened instead
- Whether it fails consistently or occasionally

## Suggesting features or improvements

Open an issue describing:
- The problem you ran into
- What you think would solve it
- Any alternatives you considered

## Design principles

Changes to this plugin must preserve:
- **Pure markdown** — no scripts, no dependencies, no platform-specific code
- **Cross-platform** — must work identically on Mac, Linux, and Windows
- **Cost-aware** — Sonnet for exploration, Opus only for planning
- **Privacy-first** — never read files outside the repo, never log secrets
- **Honest** — if a task is trivial, say so instead of inflating the plan

## Architecture

| File | Purpose |
|------|---------|
| `.claude-plugin/plugin.json` | Plugin manifest |
| `commands/trekresearch.md` | The `/trekresearch` slash command — research orchestration |
| `commands/trekplan.md` | The `/trekplan` slash command — planning orchestration |
| `commands/trekexecute.md` | The `/trekexecute` slash command — execution orchestration |
| `agents/*.md` | 19 specialized agents for research, exploration, review, and orchestration |
| `templates/plan-template.md` | Structured plan output format |
| `templates/research-brief-template.md` | Research brief format with triangulation and confidence |
| `templates/spec-template.md` | Spec file format |
| `templates/session-spec-template.md` | Session spec format for headless execution |
| `templates/headless-launch-template.md` | Launch script template |

The command files are the core. All logic lives in markdown.

## Testing locally

```bash
claude --plugin-dir /path/to/trekplan
# Then in the session:
/trekresearch <research question>
/trekplan <describe a task>
/trekexecute <path to plan>
```

Verify:
- `/trekresearch`: Research agents spawn, brief written to `.claude/research/`
- `/trekplan`: Exploration agents spawn in parallel, plan follows template, plan written to `.claude/plans/`, adversarial review runs
- `/trekexecute`: Steps execute with verify + checkpoint per step