# {{PROJECT_NAME}}

## Project Status

{{PROJECT_NAME}} is managed with a brief-first, Specify-first workflow pack.

- **Workflow pack version**: {{PACK_VERSION}}
- **Core contract version**: {{CORE_VERSION}}
- **Selected profile**: {{PROFILE_NAME}} (v{{PROFILE_VERSION}})
- **Primary product**: {{PRIMARY_PRODUCT}}
- **Legacy surface**: {{LEGACY_SURFACE}}
- **Roadmap**: no new feature work should target a legacy surface unless it is explicitly approved

## Portable Contract

The repo-local contract is the source of truth for both humans and agents:

- `workflow-pack.json` defines the selected profile, add-ons, and workflow gates
- `.workflow-pack/manifest.json` records the installed core, generated surfaces, and recommended skill bundles
- `AGENTS.md` and `CLAUDE.md` explain the policy in plain language
- `.github/copilot-instructions.md` and `.github/agents/` define the GitHub Copilot surface

## Official Development Model

Specify is the canonical orchestrator for non-trivial work in this repository, but it starts only after the brief is locked.

- Start new work with `{{BRIEF_ENTRYPOINT}} <initial-feature-description>`
- Generate `{{BRIEF_ARTIFACT}}` before any planning or implementation
- Run `{{WORKFLOW_ENTRYPOINT}} <slug>` only after the brief is approved
- The slug written in `{{BRIEF_ARTIFACT}}` is the canonical feature identifier
- Canonical feature artifacts live in `{{ARTIFACT_DIR}}/<feature-branch>/`
- Legacy PRD/SPEC flows are not the source of truth

### Official Workflow

1. Start with `{{BRIEF_ENTRYPOINT}} <initial-feature-description>`
2. Use the mandatory `brainstorming` skill to refine the feature
3. Generate `{{BRIEF_ARTIFACT}}` with a canonical slug
4. Run `{{WORKFLOW_ENTRYPOINT}} <slug>` only if the provided slug matches the slug in `{{BRIEF_ARTIFACT}}`
5. Run `/speckit.specify`
6. Run `/speckit.clarify` when critical ambiguity remains
7. Run `/speckit.plan`
8. Run `/speckit.tasks`
9. Run `/speckit.analyze`
10. Run `/speckit.implement`
11. Run validation gates
12. Run a mandatory fix round
13. Re-run validation gates
14. Update `TEST_REPORT.md`
15. Update `REVIEW_REPORT.md`
16. Generate `SNAPSHOT.md` as the last step

The workflow must stop when:

- `{{BRIEF_ARTIFACT}}` is missing or empty
- the requested workflow slug does not match the slug in `{{BRIEF_ARTIFACT}}`
- critical ambiguity remains unresolved after clarification
- a new technology outside the approved stack is required
- an objective gate fails and cannot be resolved automatically

## Supported Workspaces

{{SUPPORTED_WORKSPACES}}

## Supported Platforms

{{SUPPORTED_PLATFORMS}}

## Active Stack

### Backend

{{BACKEND_STACK}}

### Frontend

{{FRONTEND_STACK}}

## Repository Map

{{REPOSITORY_MAP}}

## Brief Contract

`{{BRIEF_ARTIFACT}}` must contain at least:

- Feature title
- `- Slug: \`feature-slug\``
- Problem or opportunity
- Goal
- Initial scope
- Out of scope
- Constraints and risks
- Success criteria
- Open questions that are not blocking

## Required Skills

Required skills for the workflow baseline:

{{REQUIRED_SKILLS}}

Bundled repo-local skills for this starter:

{{BUNDLED_SKILLS}}

Recommended bundles for richer orchestration:

{{RECOMMENDED_SKILLS}}

Skill precedence:

1. agent-native global skills, when supported, such as `$CODEX_HOME/skills`, `~/.claude/skills`, or `~/.config/opencode/skills`
2. repo-local mirrors under `{{LOCAL_SKILLS_DIR}}/`, `.claude/skills/`, `.opencode/skills/`, and `.agents/skills/`
3. explicit failure from `doctor` when neither is available

## Required Artifacts

Each non-trivial feature branch must maintain these artifacts in `{{ARTIFACT_DIR}}/<feature-branch>/`:

- `spec.md`
- `plan.md`
- `tasks.md`
- `checklists/` when needed
- `TEST_REPORT.md`
- `REVIEW_REPORT.md`
- `SNAPSHOT.md`

## Quality Gates

### Blocking Gates

{{BLOCKING_GATES}}

Coverage must satisfy the repository threshold, which is currently `{{COVERAGE_THRESHOLD}}%`.

### Observational Gates

{{OBSERVATIONAL_GATES}}

Frontend validation when applicable:

{{FRONTEND_VALIDATION_NOTE}}

## Multi-Agent Coordination

When multiple agents or tools collaborate in this repo:

1. Claim ownership of files or a subsystem before editing
2. Do not overwrite or revert another contributor's work without explicit approval
3. Update shared artifacts in this order: `BRIEF.md`, workflow artifacts, tests/reports, `SNAPSHOT.md`
4. Re-run relevant validation before handing work off
5. Record blockers and assumptions in repo artifacts rather than private chat only

## Technology Selection

Do not introduce new technology silently.

When a change requires a technology that is not already part of the approved stack:

1. Record the need in `research.md`
2. Compare realistic alternatives
3. Evaluate maturity, adoption, documentation, lock-in, and cost
4. Prefer tools that are well reviewed and offer a viable free tier
5. Stop and request explicit approval before adding the technology to the plan or implementation

## Recommended Skills Beyond The Baseline

- `playwright`
- `playwright-interactive`
- `screenshot`
- `doc`

## Legacy Commands

{{LEGACY_COMMANDS}}

Use `{{BRIEF_ENTRYPOINT}}` first, then `{{WORKFLOW_ENTRYPOINT}}`.