# Contributing to ultraplan-local

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/ultraplan-local.md` | The `/ultraplan-local` slash command — workflow orchestration |
| `agents/*.md` | Specialized agents for exploration, review, and orchestration |
| `templates/plan-template.md` | Structured plan output format |
| `templates/spec-template.md` | Spec file format |

The command file is the core. All planning logic lives in markdown.

## Testing locally

```bash
claude --plugin-dir /path/to/ultraplan-local
# Then in the session:
/ultraplan-local <describe a task>
```

Verify:
- Exploration agents spawn in parallel
- Plan follows the template structure
- Plan file is written to `.claude/plans/`
- Adversarial review runs (plan-critic + scope-guardian)