Plan: Design Phase Asset Evidence

Initial Situation

Closed grill/backlog artifacts define one delivery chain: repo settings authority, repo asset management skill, route-gated design-phase, backlog visual evidence, and delivery/PR evidence. No previous plan existed.

Decision Ledger

Spec reviewed and patched after readonly review.
.devpunks/settings.json is canonical when present; wiki backlog-provider pages are not authority.
Reusable skills are edited in /Users/stefan/Desktop/repos/wearedevpunks-skills first, then synced into Harness.
Full parallel mode is allowed only across disjoint write scopes.
Skill edits must stay very concise and follow writing-great-skills.

Codebase Findings

Scaffold init lives in apps/cli/src/scaffold/stage.ts; provider prompt currently only covers backlog provider.
CLI checks use ensureToolsInstalled in apps/cli/src/core/tools.ts.
Update alignment lives in apps/cli/src/update/run.ts.
Skill catalog lives in apps/cli/src/data/catalog/skills.ts; sync command is bun run sync:skills.
Current visual screenshot contract is in implement-spec/references/ui-screenshot-evidence.md.

Dependency Graph

T1 ─┬─ T3 ─┬─ T5 ── T7 ── T8
    ├─ T4 ─┘
    └─ T6 ─┘
T2 ─┴─ T3/T4

Parallel Execution Waves

Wave	Tasks	Can start when
1	T1, T2	Immediately
2	T3, T4, T6	T1 and T2 complete
3	T5	T3, T4, and T6 complete
4	T7	T5 complete
5	T8	T7 complete

Tasks

T1: Repo Settings Provider Authority

depends_on: []
location: apps/cli/src/scaffold/stage.ts, apps/cli/src/scaffold/stage.test.ts, apps/cli/src/update/run.ts, apps/cli/src/update/run.test.ts, apps/cli/src/core/tools.ts, .devpunks/settings.json
description: Add canonical repo settings for backlog provider, asset provider slug, repository manager, and required tools. Scaffold init prompts for repository manager, persists settings, backfills from existing hints when missing, and validates selected provider CLI like other required tools.
validation: Repo settings precedence, backfill, prompt persistence, and required-tool checks are covered by public CLI/scaffold behavior tests.
status: Completed
log:
2026-06-25: Added repo settings authority for scaffold/update: init prompts for repository manager, writes .devpunks/settings.json, update backfills clear legacy wiki provider pins, and required-tool validation includes repo settings tools.
2026-06-25: Review found two provider-setting blockers. Fixed Bitbucket to require no generic CLI and changed legacy wiki backfill to surface conflicting provider hints instead of guessing.
files edited/created:
apps/cli/src/scaffold/stage.ts
apps/cli/src/scaffold/stage.test.ts
apps/cli/src/update/run.ts
apps/cli/src/update/run.test.ts
apps/cli/src/core/tools.ts
apps/cli/src/core/tools.test.ts
backlog_item_id: IP-282
backlog_item_url: https://linear.app/devpunks/issue/IP-282/repo-settings-and-scaffold-flows-own-provider-configuration
relation_mode: native
assigned_skills: [effect-authoring, effect-best-practices, quality-types, codebase-design, simplify, tdd, turborepo]
tdd_status: required
tdd_target: Scaffold/update resolves .devpunks/settings.json before wiki/inferred provider hints and includes repository manager CLI requirements.
red_command: bun --cwd apps/cli test -- src/scaffold/stage.test.ts src/core/tools.test.ts src/update/run.test.ts
expected_red_failure: No settings-backed provider/repository manager behavior exists.
green_command: bun --cwd apps/cli test -- src/scaffold/stage.test.ts src/core/tools.test.ts src/update/run.test.ts
reason_not_testable:
red_evidence: bun --cwd apps/cli test -- src/scaffold/stage.test.ts src/core/tools.test.ts src/update/run.test.ts failed as expected: unknown provider CLI gh, missing .devpunks/settings.json, and no settings-backed glab validation in update.
green_evidence: bun --cwd apps/cli test -- src/scaffold/stage.test.ts src/core/tools.test.ts src/update/run.test.ts passed after review fixes: 3 files, 53 tests.
codebase_design_notes: Put repo settings behind a small read/write seam; CLI prompt/update callers should not parse provider hints themselves.
review_mode: cli

T2: Shared Repo Asset Management Skill

depends_on: []
location: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/repo-asset-management/**
description: Create concise internal skill with progressive disclosure and provider references for GitHub, GitLab, Azure, and Bitbucket. Include attachment decision rules: backlog attachments first, repo-provider attachments when backlog attachment is unavailable.
validation: Skill has short entrypoint, provider refs, no duplicated long provider prose, preserves known provider facts, and records an acceptance-mapping checklist in implementation notes.
status: Completed
log:
2026-06-25: Completed in source skill repo via worker 019efe15-1d6d-7ed3-a646-1c285937d53d. Created concise entrypoint with provider-specific progressive disclosure. Acceptance map: backlog attachments preferred; repo-provider fallback; GitHub, GitLab, Azure, and Bitbucket provider refs; preserved provider facts.
files edited/created:
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/repo-asset-management/SKILL.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/repo-asset-management/references/acceptance.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/repo-asset-management/references/azure.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/repo-asset-management/references/bitbucket.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/repo-asset-management/references/github.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/repo-asset-management/references/gitlab.md
backlog_item_id: IP-287
backlog_item_url: https://linear.app/devpunks/issue/IP-287/repo-asset-management-skill-owns-provider-asset-guidance
relation_mode: native
assigned_skills: [writing-great-skills, simplify]
tdd_status: not_applicable
tdd_target: Static skill content review proves progressive disclosure and provider coverage.
red_command:
expected_red_failure:
green_command: test -f /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/repo-asset-management/SKILL.md && rg -n "backlog attachments|repo-provider|GitHub|GitLab|Azure|Bitbucket" /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/repo-asset-management
reason_not_testable: Markdown skill authoring has no runtime public interface.
red_evidence:
green_evidence: test -f /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/repo-asset-management/SKILL.md && rg -n "backlog attachments|repo-provider|GitHub|GitLab|Azure|Bitbucket" /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/repo-asset-management passed.
2026-06-25: test -f /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/repo-asset-management/SKILL.md && rg -n "backlog attachments|repo-provider|GitHub|GitLab|Azure|Bitbucket" /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/repo-asset-management exited 0. Output covered entrypoint attachment rules and all provider refs/facts.
codebase_design_notes: Provider details live behind one skill interface; phase skills reference the skill instead of copying commands.
review_mode: cli

T3: Design Phase Skill

depends_on: [T1, T2]
location: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/design-phase/**
description: Create concise route-gated design-phase skill with router and phase files for intake, grill, prototype, approval, backlog, and delivery-handoff. Include route contract, staleness rules, artifact approval contract, subagent prototype delegation, repo asset skill usage, backlog conversion, and delivery activation.
validation: Skill files encode every SPEC acceptance criterion without eager loading child phases, and implementation notes include an acceptance-mapping checklist for router contract, low-confidence intake, direct entry, approval blocking, backlog conversion, and delivery activation.
status: Completed
log:
2026-06-25: Created concise route-gated design-phase in the source skills repo via worker 019efe20-d2c0-7cd3-a183-b4065f75031f. Entrypoint loads router first; phase files cover intake, lean grill, prototype delegation, approval, backlog conversion, and delivery activation.
files edited/created:
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/design-phase/SKILL.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/design-phase/phases/router.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/design-phase/phases/intake.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/design-phase/phases/grill.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/design-phase/phases/prototype.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/design-phase/phases/approval.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/design-phase/phases/backlog.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/design-phase/phases/delivery-handoff.md
backlog_item_id: IP-277
backlog_item_url: https://linear.app/devpunks/issue/IP-277/design-phase-skill-supports-the-full-route-gated-design-lifecycle
relation_mode: native
assigned_skills: [writing-great-skills, requirements-grill, design-taste-frontend, gpt-taste, image-to-code, imagegen-frontend-web, imagegen-frontend-mobile, write-backlog, delivery-phase, simplify]
tdd_status: not_applicable
tdd_target: Static skill contract review proves route-gated lifecycle behavior.
red_command:
expected_red_failure:
green_command: test -f /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/design-phase/phases/router.md && rg -n "router output|phase handoff|staleness|low-confidence|approved artifact|delivery-phase" /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/design-phase
reason_not_testable: Markdown skill authoring has no runtime public interface.
red_evidence:
green_evidence: test -f /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/design-phase/phases/router.md && rg -n "router output|phase handoff|staleness|low-confidence|approved artifact|delivery-phase" /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/design-phase passed; output covered router/staleness, intake low-confidence, approved artifact sets, backlog conversion, and delivery-phase activation.
codebase_design_notes: Router is the public seam; phase files contain phase-local child skill delegation.
review_mode: cli

T4: Existing Skill Visual Evidence Call Sites

depends_on: [T1, T2]
location: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/**, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/implement-spec/**, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/delivery-phase/**
description: Update write-backlog, implement-spec, and delivery-phase to reference repo asset management for approved artifact links, backlog attachments/fallbacks, before/after UI evidence, and PR-ready handoff.
validation: Existing skills mention repo asset management at the right decision points, carry backlog/PR visual evidence requirements, avoid duplicated provider-specific commands, and implementation notes include an acceptance-mapping checklist for IP-292/IP-294.
status: Completed
log:
2026-06-25: Updated existing call-site skills in source repo via worker 019efe20-c3a2-7470-8977-a5db0357c936. write-backlog now carries approved visual artifacts into backlog items with backlog attachments first and repo-provider fallback. implement-spec routes UI before/after durable asset storage through repo-asset-management and keeps PR-ready UI Evidence links. delivery-phase carries approved artifacts and UI evidence through implement, handoff, and closeout.
files edited/created:
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/SKILL.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/REFERENCE.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/implement-spec/SKILL.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/implement-spec/references/ui-screenshot-evidence.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/implement-spec/assets/IMPLEMENTATION-NOTES-TEMPLATE.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/delivery-phase/SKILL.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/delivery-phase/phases/implement.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/delivery-phase/phases/closeout.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/delivery-phase/references/phase-handoff.md
backlog_item_id: IP-292, IP-294
backlog_item_url: https://linear.app/devpunks/issue/IP-292/design-backlog-flow-carries-approved-visual-artifacts-into-backlog
relation_mode: native
assigned_skills: [writing-great-skills, write-backlog, implement-spec, delivery-phase, simplify]
tdd_status: not_applicable
tdd_target: Static skill review proves durable visual evidence is carried into backlog, implementation notes, closeout, and PR handoff.
red_command:
expected_red_failure:
green_command: rg -n "repo-asset-management|repo asset|approved artifact|before/after|UI Evidence" /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/implement-spec /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/delivery-phase
reason_not_testable: Markdown skill authoring has no runtime public interface.
red_evidence:
green_evidence: rg -n "repo-asset-management|repo asset|approved artifact|before/after|UI Evidence" /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/implement-spec /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/delivery-phase passed. Review scan for provider command duplication found only the guard against copying provider CLI commands.
codebase_design_notes: Centralize provider behavior in one skill; call sites carry only when to invoke it.
review_mode: cli

T5: Sync Skills And Catalog

depends_on: [T3, T4]
location: apps/cli/skills/**, apps/cli/src/data/catalog/skills.ts, apps/cli/src/data/catalog/packs.ts
description: Verify source skill repo changes are isolated, commit/push source skill changes, sync shared skill source into Harness, add catalog entries/packs for new skills, and preview scaffold update behavior for active mirrors without rewriting unrelated generated agent files.
validation: Source repo status/push evidence is recorded before bun run sync:skills; catalog references valid synced directories.
status: Completed
log:
2026-06-25: Committed and pushed source skill repo changes as 6b609de feat: add design phase asset evidence skills.
2026-06-25: Ran bun run sync:skills; Harness synced design-phase, repo-asset-management, and existing call-site skill edits into apps/cli/skills.
2026-06-25: Added catalog entries and pack membership for design-phase and repo-asset-management.
2026-06-25: Previewed active .agents/skills update with bundled baseline. Preview would add the two skills, but also rewrite 100+ managed harness files because this repo has baseline drift and local-edited generated agent files, so the active mirror apply was intentionally not run.
files edited/created:
apps/cli/skills/phases/design-phase/**
apps/cli/skills/agnostic/repo-asset-management/**
apps/cli/skills/agnostic/requirements/write-backlog/**
apps/cli/skills/agnostic/planning/implement-spec/**
apps/cli/skills/phases/delivery-phase/**
apps/cli/src/data/catalog/skills.ts
apps/cli/src/data/catalog/packs.ts
backlog_item_id: IP-277, IP-287
backlog_item_url: https://linear.app/devpunks/issue/IP-277/design-phase-skill-supports-the-full-route-gated-design-lifecycle
relation_mode: native
assigned_skills: [turborepo, simplify, writing-great-skills]
tdd_status: not_applicable
tdd_target: Sync/catalog validation proves new skills are distributable.
red_command:
expected_red_failure:
green_command: git -C /Users/stefan/Desktop/repos/wearedevpunks-skills status --short && bun run sync:skills && bun run check --filter=@punks/cli
reason_not_testable: Generated/synced catalog and static skill files.
red_evidence:
green_evidence: Source skills pushed: git -C /Users/stefan/Desktop/repos/wearedevpunks-skills log -1 --oneline reported 6b609de feat: add design phase asset evidence skills. bun run sync:skills succeeded. test -f apps/cli/skills/phases/design-phase/SKILL.md && test -f apps/cli/skills/agnostic/repo-asset-management/SKILL.md && rg -n "design-phase|repo-asset-management" apps/cli/src/data/catalog/skills.ts apps/cli/src/data/catalog/packs.ts apps/cli/.devpunks-cache/skills-sync.json passed. bun run check --filter=@punks/cli passed.
codebase_design_notes: Catalog is the distribution seam; no phase skill should be hardcoded elsewhere.
review_mode: cli

T6: Wiki Provider Authority Cleanup And Docs

depends_on: [T1]
location: apps/wiki/backlog-provider.md, apps/wiki/content/docs/project/backlog-provider.mdx, apps/wiki/content/docs/project/meta.json, docs/README.md, docs/runbooks/dp-cli-scaffolding.md
description: Remove wiki provider pages as authority and document .devpunks/settings.json as the provider source for scaffold/update and visual assets.
validation: Wiki route metadata no longer treats backlog-provider page as a configuration surface; docs explain repo settings path.
status: Completed
log:
2026-06-25: Demoted wiki backlog-provider pages to legacy migration hints, removed backlog-provider from project route metadata, and documented .devpunks/settings.json as the provider source for scaffold/update, backlog writing, visual assets, and required-tool validation.
files edited/created:
apps/wiki/backlog-provider.md
apps/wiki/content/docs/project/backlog-provider.mdx
apps/wiki/content/docs/project/meta.json
docs/README.md
docs/runbooks/dp-cli-scaffolding.md
backlog_item_id: IP-282
backlog_item_url: https://linear.app/devpunks/issue/IP-282/repo-settings-and-scaffold-flows-own-provider-configuration
relation_mode: native
assigned_skills: [docs-onboarding, parallel-research, writing-great-skills, docs-ingest-phase, next-best-practices, next-cache-components, simplify]
tdd_status: not_applicable
tdd_target: Documentation/routing no longer presents wiki backlog provider as authority.
red_command:
expected_red_failure:
green_command: bun run check --filter=@punks/wiki
reason_not_testable: Docs/routing cleanup.
red_evidence:
green_evidence: bun run check --filter=@punks/wiki passed after formatting touched docs/spec artifacts, including apps/wiki/content/docs/project/grilling/ui-design-phase-flow-grill-status.md.
codebase_design_notes: Settings docs are explanatory; CLI settings reader is the authority.
review_mode: cli

T7: Full Validation And Implementation Notes

depends_on: [T5, T6]
location: apps/wiki/content/docs/project/specs/cli/IP-273-design-phase-asset-evidence/IMPLEMENTATION-NOTES.md
description: Run targeted and repo validation, fill implementation notes with RED/GREEN evidence, changed files, visual-evidence behavior, and remaining risks.
validation: Targeted CLI tests, CLI check, wiki check, and repo check results are recorded.
status: Completed
log:
2026-06-25: Full validation passed after T1-T6 and skill sync/catalog updates.
files edited/created:
apps/wiki/content/docs/project/specs/cli/IP-273-design-phase-asset-evidence/IMPLEMENTATION-NOTES.md
backlog_item_id: IP-273
backlog_item_url: https://linear.app/devpunks/issue/IP-273/design-phase-route-gated-lifecycle
relation_mode: native
assigned_skills: [delivery-phase, tdd, simplify]
tdd_status: not_applicable
tdd_target: Durable implementation note proves the delivery evidence trail.
red_command:
expected_red_failure:
green_command: bun --cwd apps/cli test -- src/scaffold/stage.test.ts src/core/tools.test.ts src/update/run.test.ts && bun run check --filter=@punks/cli && bun run check --filter=@punks/wiki && bun run check:repo
reason_not_testable: Evidence aggregation after implementation.
red_evidence:
green_evidence: bun --cwd apps/cli test -- src/scaffold/stage.test.ts src/core/tools.test.ts src/update/run.test.ts && bun run check --filter=@punks/cli && bun run check --filter=@punks/wiki && bun run check:repo passed. Targeted CLI tests: 3 files, 53 tests. CLI/wiki checks and repo formatting/lint all passed.
codebase_design_notes: Notes are the resume/closeout seam for future delivery-phase routing.
review_mode: cli

T8: Review, Linear Closeout, And PR Evidence

depends_on: [T7]
location: changed diff, Linear IP-273/IP-274/IP-275/IP-276/IP-277/IP-282/IP-287/IP-292/IP-294
description: Run mandatory code/skill review, fix blockers, update Linear issue states/comments with evidence, and prepare PR-ready before/after visual evidence guidance when UI evidence applies.
validation: Review has no blocking findings; Linear issues reflect implementation evidence.
status: Completed
log:
2026-06-25: Code review found two P2 provider settings issues; both were fixed and rechecked with no findings.
2026-06-25: Docs-ingest routed private/internal and verified spec artifacts, wiki provider note, root docs, and scaffold runbook as current.
2026-06-25: Linear closeout comments posted and IP-273, IP-274, IP-275, IP-276, IP-277, IP-282, IP-287, IP-292, and IP-294 moved to Done.
files edited/created:
apps/wiki/content/docs/project/specs/cli/IP-273-design-phase-asset-evidence/PLAN.md
apps/wiki/content/docs/project/specs/cli/IP-273-design-phase-asset-evidence/IMPLEMENTATION-NOTES.md
backlog_item_id: IP-276
backlog_item_url: https://linear.app/devpunks/issue/IP-276/visual-evidence-handoff-for-design-backlog-and-pr-review
relation_mode: native
assigned_skills: [review-phase, delivery-phase, simplify]
tdd_status: not_applicable
tdd_target: Review and tracker closeout prove delivered scope.
red_command:
expected_red_failure:
green_command: git diff --check
reason_not_testable: Review/tracker closeout.
red_evidence:
green_evidence: git diff --check passed during review. Targeted reviewer re-check reported no findings after Bitbucket/no-CLI and ambiguous-backfill fixes. Linear issues were updated to Done.
codebase_design_notes: Closeout consumes prior evidence, no new module seam.
review_mode: cli

Testing Strategy

RED/GREEN for behavior-changing CLI settings work in T1.
Static skill checks via rg and skill review for T2-T4.
Distribution checks through bun run sync:skills and bun run check --filter=@punks/cli.
Docs route/check validation through bun run check --filter=@punks/wiki.
Final repo-level check with bun run check:repo if time permits.

Risks And Mitigations

Skill sync may require catalog shape updates: inspect current skills.ts before patching.
Wiki provider pages conflict today: delete or demote authority only after settings exists.
Provider CLI checks can overreach: keep mapping minimal (github -> gh, gitlab -> glab, azure -> az, bitbucket -> documented external path) and surface unsupported CLI cases clearly.
Markdown-only skill changes can drift verbose: apply writing-great-skills pruning after drafting.

Unresolved Questions

None blocking. Linear milestone assignment remains deferred from backlog creation because connector required an existing milestone UUID.

Design Phase Asset Evidence Plan