trellis-before-dev

name	trellis-before-dev
description	Read all task artifacts and specs before writing code. Outputs implementation constraints. Use after task.py start and before any source editing — the before-dev gate is mandatory and blocks code changes until satisfied.

Trellis Before Dev

Preconditions

• Task status is in_progress (task.py start has been run).
• Planning artifacts are complete (prd.md, implement.md, design.md if L4/L5).
• implement.md already records the user's implementation approval:
  • approved is checked
  • Allowed to run task.py start? -> yes is checked
  • user message / timestamp / summary approved are filled

Core Rules

This skill is a gate. You MUST NOT edit source code before completing it. Reading is allowed. Writing code is forbidden until this skill finishes.

Workflow

1. Read prd.md — understand the goal, scope, acceptance criteria, and out-of-scope items.
2. Read design.md (if present) — understand architecture, data flow, contracts, and trade-offs.
3. Read implement.md — understand execution strategy, review gate contract, and validation commands.
4. Verify Implementation Approval — confirm implement.md contains the recorded user approval before any source editing.
5. Read implement.jsonl entries — understand which specs and research files are curated for implementation context.
   • implement.jsonl / check.jsonl must contain only spec files and research files.
   • Do NOT duplicate task artifacts (prd.md, design.md, implement.md, finish.md) in JSONL; hooks already inject those.
6. Read relevant specs — use .trellis/spec/index.md to route to the right spec files. Read the specific guideline files, not just the index.
7. Read common mistakes — always read .trellis/spec/guides/ai-behavior/common-mistakes.md when present and translate relevant common mistakes into concrete before-dev.md constraints or Must NOT items.
8. Read relevant research — any research/*.md files referenced by the task.
9. Read developer preferences when available — if .trellis/.developer points to a workspace or there is exactly one .trellis/workspace/<name>/preferences.md, load it and apply only the preferences that do not conflict with task artifacts or team specs.
10. Output implementation constraints — write before-dev.md with a concise list of what must be true during implementation.
11. Write scope-manifest.json — create the sibling machine-readable scope contract before editing source.
12. Confirm task is in_progress — verify status before proceeding.

Spec Reading

# Discover packages and their spec layers
python3 ./.trellis/scripts/get_context.py --mode packages

# Read spec index for each relevant package
cat .trellis/spec/<package>/<layer>/index.md

# Read the specific guideline files listed in the index
cat .trellis/spec/<package>/<layer>/<guideline>.md

# Always read shared guides
cat .trellis/spec/guides/index.md

# Always read repeated workflow mistakes when available
cat .trellis/spec/guides/ai-behavior/common-mistakes.md

The index is NOT the goal — it points to the actual guideline files. Read those files to understand the coding standards and patterns.

Output Format

Implementation Constraints

# Before-Dev Constraints: [Task Title]

## Task Context
- Task level: [L0-L5]
- Goal: [one sentence from prd.md]

## Scope Boundaries
- In scope: [from prd.md]
- Out of scope: [from prd.md]

## Spec Constraints
- [spec file]: [key constraint]
- [spec file]: [key constraint]

## Design Constraints
- [from design.md, if present]

## Implementation Strategy
- Mode: [from implement.md]
- TDD: [yes/no]
- Review gates: [selected gates from contract]

## Acceptance Criteria
- [AC 1]
- [AC 2]

## Observable Outcomes
- [what the user or operator must be able to observe after implementation]

## Must NOT
- [boundary from prd.md or implement.md]

Scope Manifest

Write scope-manifest.json next to before-dev.md:

{
  "version": 1,
  "level": "L2",
  "profile": "light",
  "declared_paths": ["src/example.py"],
  "declared_globs": ["tests/example_*.py"],
  "high_risk_allowed": ["api/example.py"],
  "out_of_scope": ["auth policy changes"],
  "workstreams": []
}

Rules:

• declared_paths are exact files or directories that the implementation may touch.
• declared_globs are scoped glob patterns for generated or grouped files.
• At least one of declared_paths or declared_globs must be non-empty.
• high_risk_allowed is a path/glob list and must cover declared API, auth, schema, migration, shared-types, contract, or proto scope explicitly allowed by the PRD/implement plan.
• out_of_scope captures boundaries from PRD, grill/design, or implement plan and must contain at least one boundary.
• workstreams is an optional array of {name, owner} objects. When scope-manifest.json declares workstreams, implementer/checker agent results must include a matching workstream field. For L5/orchestrated tasks using parallel agents, each workstream should have a name and an owner (the agent responsible).

Quality Bar

• All task artifacts have been read (prd.md, design.md, implement.md, JSONL entries).
• The implementation approval record is present in implement.md.
• scope-manifest.json is written and matches before-dev.md.
• Relevant spec files have been read (not just the index).
• Relevant common mistakes have been translated into concrete constraints and Must NOT items.
• Developer preferences are loaded when available and only applied within team/spec boundaries.
• Implementation constraints are specific and actionable.
• Observable outcomes to preserve or prove are captured before coding starts.
• The task status is confirmed as in_progress.
• No source code has been edited before this skill completes.

If any artifact is missing, report it before proceeding. Missing design.md is acceptable for L2-L3. Missing prd.md or implement.md is blocking.