# Project-Dev Workflow

## Scope

- Canonical required workflow for `project-dev` context.
- Applies to repository implementation tasks: edits, tests, and delivery checks.

## Entry commands

1. `agent-docs --docs-home "$AGENT_HOME" resolve --context startup --strict --format checklist`
2. `agent-docs --docs-home "$AGENT_HOME" resolve --context project-dev --strict --format checklist`
3. `agent-docs --docs-home "$AGENT_HOME" resolve --context task-tools --format checklist` (optional, when external technical lookup is needed)
4. `agent-docs --docs-home "$AGENT_HOME" baseline --check --target all --strict --format text` (only when strict resolve fails)

## Project validation commands

- Canonical pre-commit gate: `scripts/check.sh --pre-commit`
- Canonical minimum gate: `scripts/check.sh --all`
- Docs freshness gate (standalone): `scripts/check.sh --docs`
- CI parity guard: `scripts/check.sh --tests -- -k parity -m script_regression`
- Skill entrypoint drift guard (when workflow/tool entrypoints change):
  - `bash scripts/ci/stale-skill-scripts-audit.sh --check`
  - `scripts/check.sh --entrypoint-ownership`

Use `scripts/check.sh` modes for project-dev verification. Avoid reintroducing ad-hoc legacy script wrappers in docs/workflows.

## Deterministic flow

1. Resolve `startup` in strict mode before any implementation preflight.
2. Resolve `project-dev` in strict mode before file edits or test runs.
3. Load project-specific docs (`DEVELOPMENT.md`, repo docs) before implementation.
4. Run project-required validation commands before reporting completion (default: `scripts/check.sh --all`).
5. Use `task-tools` lookup only as a supplement, not a replacement for project-local requirements.

## Failure handling

- `startup` strict resolve fails:
  - Block code edits, commits, and delivery claims.
  - Run strict baseline check and report missing docs.
  - Resume only after required docs are present.
- `project-dev` strict resolve fails:
  - Block code edits, commits, and delivery claims.
  - Run strict baseline check and report missing docs.
  - Resume only after required docs are present.
- Project validation command fails:
  - Report failing command and key error.
  - Do not claim completion.

## Validation checklist

- [ ] `agent-docs --docs-home "$AGENT_HOME" resolve --context startup --strict --format checklist` exits 0 before edits.
- [ ] `agent-docs --docs-home "$AGENT_HOME" resolve --context project-dev --strict --format checklist` exits 0 before edits.
- [ ] Required project checks are executed and results reported (`scripts/check.sh --all` minimum).
- [ ] Failures include explicit command/error details.
