| name | dev-workflow |
| description | The full feature development cycle as a numbered checklist — from proposal through implementation, review, infosec sign-off, decision logging, and PR. Defines when each agent handoff happens, the dedicated path for infrastructure changes, and how to handle iteration loops. |
| compatibility | opencode |
Dev Workflow Skill
This skill describes the complete feature development cycle used in this project. Follow
these steps in order for any non-trivial piece of work. Each step maps to a specific skill.
Project Context
Project: gareth.photography — Static photography portfolio site for Gareth Hughes; albums defined in data/albums.ts, photos served from CDN in production, deployed to GitHub Pages as a fully static Next.js export.
Frontend: Next.js 16.2.4 (App Router, output: "export", fully static) / TypeScript 5 strict / Tailwind CSS v4 (CSS-first, @theme in app/globals.css)
Backend: None — static site only
Auth: None — fully public
Validation: N/A
Logging: None (static site)
Testing: None — verify with npm run build and npm run lint
Infra: No IaC; GitHub Pages (primary, CI deploy); S3 + CloudFront for photo CDN; Makefile for manual S3/CDN ops; GitHub Actions CI
Local dev: npm run dev — photos from public/photos/<slug>/
Compliance: None (personal portfolio)
Data classes: All content is public
Encryption: at rest S3 default / in transit HTTPS (CloudFront + GitHub Pages)
Repo structure: app/, components/, data/, lib/, scripts/, public/photos/, .github/workflows/
Module structure: Thin pages in app/ delegate to components in components/. All data is static in data/albums.ts. Photo URLs always go through photoUrl() in lib/photos.ts.
Key rules:
- Never construct photo URLs manually — always use
photoUrl(slug, filename) from lib/photos.ts
- Always regenerate dimensions with
node scripts/gen-dimensions.mjs after adding photos — never hardcode them
- Tailwind v4 CSS-first — no
tailwind.config.*; all tokens in app/globals.css
NEXT_PUBLIC_CDN_URL is the only env var; accessed via lib/photos.ts only- TypeScript strict mode — no
any, no implicit returns
- Verify changes with
npm run build + npm run lint (no test suite)
External integrations: CloudFront CDN (cdn.gareth.photography), S3 photo storage, GitHub Pages hosting
Key entities: Album (public), Photo (public) — see data/types.ts
Known gotchas: Tailwind v4 syntax differs from v3. Next.js 16 has breaking API changes — read node_modules/next/dist/docs/ before writing code. params in dynamic routes is a Promise<{slug}> (async params pattern).
Open onboarding gaps: 5 items — see CLAUDE.md ## Onboarding Notes
The Full Feature Development Cycle
Step 1 — Design (Architect skill)
When: Before writing any code for a non-trivial change.
Use the architect skill to:
- Determine whether the change warrants a proposal (see the architect skill's "When to Write
a Proposal" section — note this includes infra-only changes such as new IAM policies,
network changes, new resources)
- If yes: write a proposal in
docs/proposals/NNNN-short-title.md, including the
Infrastructure Addendum if any infra is touched
- Get the proposal reviewed (share with the team / another agent) and update status to
Accepted
- Create any ADR(s) that the proposal produces in
docs/decisions/
Skip this step only for: trivial bug fixes, copy changes, or configuration tweaks that
do not affect architecture, module boundaries, schema, infra, or security posture.
Handoff to Step 2 when: the proposal status is Accepted (or the change is confirmed
as trivial).
Step 2 — Implementation (Developer skill)
When: Proposal is accepted (or change is confirmed trivial).
Use the developer skill to:
- Create a new branch:
git checkout -b feature/NNNN-short-title (adjust the branch
naming convention to match your project's standard, or use the convention defined in
your CLAUDE.md)
- Follow the red-green-refactor TDD cycle for every unit of behaviour:
- Write a failing test first
- Write the minimum code to make it pass
- Refactor while keeping tests green
- Follow all project conventions (thin controllers, typed API client, ConfigService,
no
any, no implicit returns, structured logging, validated DTOs)
- For infra changes: edit IaC under
infra/, run terraform plan (or equivalent)
locally, capture the plan summary for the PR description. Never apply to a shared
environment from a developer machine
- Call out any new dependencies (npm packages, Terraform modules, providers) explicitly
before adding them
- Run the full test suite before considering the implementation complete
Handoff to Step 3 when: all tests pass and the branch is ready for review.
Step 3 — Code Review (Reviewer skill)
When: Implementation is complete and tests are green.
Use the reviewer skill to:
- Trace each Acceptance Criterion from the proposal to a covering test
- Review all staged / branch changes for correctness, security, performance, IaC safety,
observability, and convention adherence
- Return a verdict: PASS / PASS WITH COMMENTS / BLOCK
If BLOCK or Major findings:
- Return to Step 2 (developer) to address all Blocker and Major findings
- Re-run the reviewer skill after fixes
- Repeat until the verdict is PASS or PASS WITH COMMENTS
If PASS or PASS WITH COMMENTS:
- Acknowledge Minor/Suggestion items (fix or consciously defer)
- Proceed to Step 4
Handoff to Step 4 when: reviewer verdict is PASS or PASS WITH COMMENTS with all
Blockers and Majors resolved.
Step 4 — Infosec Sign-Off (Infosec skill)
When: Code review has passed AND the change touches any of:
- Authentication, authorisation, or session handling
- User data (read, write, export, deletion)
- Cryptography (encryption, hashing, key management, secrets)
- Logging or audit trails (added, removed, or modified)
- Infrastructure (IAM, network, secrets manager, KMS, public endpoints)
- A new external integration
- A new dependency that handles credentials, crypto, or PII
For pure UI / pure refactor / pure docs changes with none of the above, skip this step.
Use the infosec skill to:
- Run the project's compliance review against the diff (e.g. ISO27001 controls if applicable)
- Verify no plaintext secrets, no over-broad IAM, no PII in logs, no missing auth guards,
no insecure crypto choices
- Return a verdict: APPROVED / REQUIRES CHANGES / APPROVED WITH EXCEPTION
If REQUIRES CHANGES:
- Return to Step 2 to fix
- Re-run infosec after fixes
- Document any APPROVED WITH EXCEPTION findings as ADRs in Step 5
Handoff to Step 5 when: infosec verdict is APPROVED or APPROVED WITH EXCEPTION
(with exceptions queued for ADR).
Step 5 — Decision Logging (Decision Log skill)
When: Implementation is reviewed, infosec-approved, and accepted.
Use the decision-log skill to log any significant decisions made during Steps 1–4:
- Technology or library chosen
- Architectural pattern adopted
- Infrastructure topology choice
- Trade-off made between approaches
- Edge case resolution agreed
- Security exception accepted (each one becomes an ADR)
- Proposal accepted (if not already logged in Step 1)
Update any proposals in docs/proposals/ whose status is still Draft or Under Review
to Accepted, linking the ADR numbers.
Handoff to Step 6 when: all relevant ADRs are written and the index is updated.
Step 6 — Pull Request
When: Steps 1–5 are complete.
- Push the branch to remote:
git push -u origin feature/NNNN-short-title
- Open a PR targeting
main (or the project's default branch)
- In the PR description, include:
- A summary of what changed and why
- Link to the accepted proposal (if one exists)
- Link to any new ADRs created
- Test coverage summary (new tests added, all passing)
- For infra changes: the
terraform plan (or equivalent) summary
- Infosec verdict (APPROVED / APPROVED WITH EXCEPTION + ADR link)
- Ensure CI passes (including infra
plan and any IaC tests)
Iteration Reference
| Situation | Action |
|---|
| Reviewer returns BLOCK | Fix all Blockers → re-review (Step 3 → Step 2 → Step 3) |
| Infosec returns REQUIRES CHANGES | Fix → re-run infosec (Step 4 → Step 2 → Step 4) |
| Implementation reveals design flaw | Write a new proposal or amend the existing one (Step 1) before proceeding |
| New dependency needed | Call it out explicitly in Step 2; reviewer checks supply-chain in Step 3; infosec checks crypto/secrets handling in Step 4 |
| Infra-only change | Same flow — proposal must include Infrastructure Addendum; PR must include plan output |
| Trivial fix (no design impact, no infra, no security) | Start at Step 2; skip Steps 1 and 4 |
| Bug fix | Write regression test first (TDD red step), then fix (green), then review |
| Security exception accepted | Must be documented as an ADR in Step 5; reference it in the PR |
Quick Reference
Step 1 → architect skill (propose; include Infra Addendum if relevant)
Step 2 → developer skill (implement with TDD; capture plan output for infra)
Step 3 → reviewer skill (code review; loop back to Step 2 if blocked)
Step 4 → infosec skill (security/compliance sign-off; conditional — see Step 4)
Step 5 → decision-log skill (log ADRs, update proposal statuses, log any exceptions)
Step 6 → open PR (include proposal link, ADRs, plan output, infosec verdict)
