Plan: Backend Domain Structure Guardrails

Status: Complete Mode: parallel Issue: https://github.com/wearedevpunks/harness-intelligence/issues/67

Initial Situation

Issue 67 asks for a stronger shared backend-domain-structure skill for generic Python backend architecture. The Harness mirrors are still terse: they classify platform/, integrations/, and features/<domain>/, but do not fully spell out database persistence, pure domain models/events, DI/container boundaries, public API boundaries, stale aliases, or validation prompts.

The shared source repo already has local uncommitted edits under skills/agnostic/backend/backend-domain-structure that appear to cover most requested guardrails. Those edits must be inspected, completed if needed, and preserved or adjusted by their owner instead of being overwritten.

Solution Shape

Finish the shared skill source, commit and push it there, then sync Harness distribution surfaces. Keep the main SKILL.md concise and put detailed guardrails in references/layout.md. Refresh downstream mirrors only through the established source-first path, then validate text, sync metadata, and focused Harness checks.

No implementation task should edit backend app code or introduce repo-specific examples.

Resolved Decision Ledger

Codebase Findings

• Shared source: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/backend/backend-domain-structure.
• Harness CLI mirror: apps/cli/skills/agnostic/backend/backend-domain-structure.
• Active local mirror: .agents/skills/backend-domain-structure.
• Current shared source has modified SKILL.md and references/layout.md.
• Current Harness mirrors have not yet received the expanded guardrails.
• Repo docs state shared skill changes must be made in wearedevpunks-skills, pushed, then synced with bun run sync:skills.

External Research

No external package or API research is required. This is a shared skill wording and distribution change.

Dependency Graph

T0a and T0b ran in parallel for discovery and planning setup. T1 and T2a ran in parallel because their write scopes were disjoint. T2b -> T3 -> T4 remain ordered because Harness sync depends on the pushed shared-source commit.

T0a + T0b -> T1 + T2a -> T2b -> T3 -> T4

T0a: Readonly source and mirror discovery

• depends_on: []
• location: /Users/stefan/Desktop/repos/wearedevpunks-skills, apps/cli/skills, .agents/skills
• description: Map source-of-truth, Harness mirrors, catalog wiring, and current gaps for issue 67.
• validation: Discovery reports source paths, gaps, validation surfaces, and blockers without edits.
• status: Completed
• log: Readonly worker mapped source, CLI mirror, active mirror, existing catalog membership, and issue-specific gaps.
• files edited/created: none
• backlog_item_id: issue-67
• backlog_item_url: https://github.com/wearedevpunks/harness-intelligence/issues/67
• relation_mode: body-links
• assigned_skills: [parallel-research]
• tdd_status: not_applicable
• tdd_target: Readonly evidence only.
• green_command: diff -qr /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/backend/backend-domain-structure apps/cli/skills/agnostic/backend/backend-domain-structure
• reason_not_testable: Discovery task.
• green_evidence: Source, CLI mirror, and active mirror matched before implementation; catalog already included backend-domain-structure.
• codebase_design_notes: Keep catalog unchanged unless source directory or pack membership changes.
• review_mode: cli

T0b: Readonly baseline release discovery

• depends_on: []
• location: apps/cli/scripts, BASELINE_CHANGELOG.md, CHANGELOG.md
• description: Confirm sync, validation, changelog, commit, push, and baseline publish mechanics.
• validation: Discovery reports command sequence and publish blockers.
• status: Completed
• log: Readonly worker confirmed bun run sync:skills, explicit BASELINE_VERSION, clean worktree publish requirement, and gh release asset path.
• files edited/created: none
• backlog_item_id: issue-67
• backlog_item_url: https://github.com/wearedevpunks/harness-intelligence/issues/67
• relation_mode: body-links
• assigned_skills: [parallel-research]
• tdd_status: not_applicable
• tdd_target: Release mechanics evidence only.
• green_command: sed -n '1,120p' apps/cli/scripts/publish-baseline.mjs
• reason_not_testable: Discovery task.
• green_evidence: Publish script reads BASELINE_CHANGELOG.md, refuses dirty worktrees, and uses gh release.
• codebase_design_notes: Use /opt/homebrew/bin PATH in this environment so bun and gh resolve.
• review_mode: cli

T2a: Write planning artifacts

• depends_on: [T0a, T0b]
• location: apps/wiki/content/docs/project/specs/cli/issue-67-backend-domain-structure, apps/wiki/content/docs/project/specs/cli/cli-specs.md
• description: Create the routed SPEC.md, PLAN.md, and metadata for issue 67.
• validation: Planning artifacts are concise, issue-bound, and browsable from the CLI specs index.
• status: Completed
• log: Created issue 67 spec folder, spec, plan, meta, and CLI specs index row.
• files edited/created: SPEC.md, PLAN.md, meta.json, cli-specs.md
• backlog_item_id: issue-67
• backlog_item_url: https://github.com/wearedevpunks/harness-intelligence/issues/67
• relation_mode: body-links
• assigned_skills: [create-spec, create-plan]
• tdd_status: not_applicable
• tdd_target: Planning artifact quality and route inclusion.
• green_command: test -f apps/wiki/content/docs/project/specs/cli/issue-67-backend-domain-structure/SPEC.md && test -f apps/wiki/content/docs/project/specs/cli/issue-67-backend-domain-structure/PLAN.md && rg "issue-67-backend-domain-structure" apps/wiki/content/docs/project/specs/cli/cli-specs.md
• reason_not_testable: Planning docs.
• green_evidence: Files created and index row added.
• codebase_design_notes: Treat artifacts as delivery evidence, not source skill docs.
• review_mode: cli

T1: Finish shared skill source

• depends_on: [T0a]
• location: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/backend/backend-domain-structure/SKILL.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/backend/backend-domain-structure/references/layout.md
• description: Inspect existing dirty edits, complete any missing issue 67 guardrails, and keep the main skill lean with detailed classifier/boundary guidance in the reference.
• validation: The source skill covers every acceptance criterion and contains no Harness-specific paths or names.
• status: Completed
• log: Shared-source worker added the classifier, dependency, DI/container, public boundary, persistence, domain model/event, and validation guidance.
• files edited/created: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/backend/backend-domain-structure/SKILL.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/backend/backend-domain-structure/references/layout.md
• backlog_item_id: issue-67
• backlog_item_url: https://github.com/wearedevpunks/harness-intelligence/issues/67
• relation_mode: body-links
• assigned_skills: [backend-domain-structure, codebase-design, simplify, tdd]
• tdd_status: not_applicable
• tdd_target: Skill prose review proves the classifier, boundary, DI, public API, and validation prompts exist.
• red_command:
• expected_red_failure:
• green_command: git -C /Users/stefan/Desktop/repos/wearedevpunks-skills diff --check && rg -n "Layer Classifier|Dependency Injection|Public Boundaries|Validation Prompts|database persistence|domain models|lazy imports|compatibility aliases" /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/backend/backend-domain-structure
• reason_not_testable: Documentation-only shared skill wording; no runtime behavior changes.
• red_evidence:
• green_evidence: git -C /Users/stefan/Desktop/repos/wearedevpunks-skills diff --check passed; worker reported no project-specific consuming repo names.
• codebase_design_notes: Treat the skill as a public module interface for agents; keep optional depth in references/layout.md so the activation surface stays small.
• review_mode: cli

T2b: Commit and push shared source

• depends_on: [T1]
• location: /Users/stefan/Desktop/repos/wearedevpunks-skills
• description: Commit the completed shared skill source and push it so Harness sync can fetch the public source tree.
• validation: Shared source working tree only contains intended files before commit; pushed commit contains the backend skill changes.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: issue-67
• backlog_item_url: https://github.com/wearedevpunks/harness-intelligence/issues/67
• relation_mode: body-links
• assigned_skills: [simplify]
• tdd_status: not_applicable
• tdd_target: Source provenance is visible through git status/log.
• red_command:
• expected_red_failure:
• green_command: git -C /Users/stefan/Desktop/repos/wearedevpunks-skills status --short && git -C /Users/stefan/Desktop/repos/wearedevpunks-skills log -1 --oneline -- skills/agnostic/backend/backend-domain-structure
• reason_not_testable: Git provenance task, not behavior-changing code.
• red_evidence:
• green_evidence:
• codebase_design_notes: not_applicable
• review_mode: cli

T3: Sync Harness distributed skill bundle

• depends_on: [T2b]
• location: apps/cli/skills/agnostic/backend/backend-domain-structure, apps/cli/.devpunks-cache/skills-sync.json
• description: Run the established Harness skill sync so the CLI-vendored skill bundle reflects the pushed shared source.
• validation: Sync metadata records the pushed shared-skills commit and the CLI mirror contains the new classifier, DI/container, public boundary, and validation prompt sections.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: issue-67
• backlog_item_url: https://github.com/wearedevpunks/harness-intelligence/issues/67
• relation_mode: body-links
• assigned_skills: [parallel-research, simplify, tdd]
• tdd_status: not_applicable
• tdd_target: Distribution mirror matches the pushed shared source.
• red_command:
• expected_red_failure:
• green_command: bun run sync:skills && diff -qr /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/backend/backend-domain-structure apps/cli/skills/agnostic/backend/backend-domain-structure && node -e "const fs=require('fs'); const s=JSON.parse(fs.readFileSync('apps/cli/.devpunks-cache/skills-sync.json','utf8')); if(!s.commit) process.exit(1); console.log(s.commit)"
• reason_not_testable: Generated/distribution sync validation, not runtime behavior.
• red_evidence:
• green_evidence:
• codebase_design_notes: Keep distribution as a generated mirror; do not hand-edit CLI bundle content.
• review_mode: cli

T4: Align active mirror and record delivery evidence

• depends_on: [T3]
• location: .agents/skills/backend-domain-structure, apps/wiki/content/docs/project/specs/cli/issue-67-backend-domain-structure
• description: If this repo expects the active local skill mirror to match the distributed bundle, align it from apps/cli/skills. Add implementation notes only after delivery evidence exists.
• validation: Active mirror matches the CLI bundle or the reason for leaving it unchanged is recorded; focused Harness checks pass.
• status: Planned
• log:
• files edited/created:
• backlog_item_id: issue-67
• backlog_item_url: https://github.com/wearedevpunks/harness-intelligence/issues/67
• relation_mode: body-links
• assigned_skills: [backend-domain-structure, parallel-research, simplify, tdd]
• tdd_status: not_applicable
• tdd_target: Final evidence shows source, CLI mirror, and active mirror state.
• red_command:
• expected_red_failure:
• green_command: diff -qr apps/cli/skills/agnostic/backend/backend-domain-structure .agents/skills/backend-domain-structure && bun run --cwd apps/cli test src/content/content.test.ts && git diff --check
• reason_not_testable: Mirror/docs evidence task, not behavior-changing code.
• red_evidence:
• green_evidence:
• codebase_design_notes: Active mirror alignment is a consumer-surface proof, not a source edit.
• review_mode: cli

Final Validation

Testing Strategy

• git -C /Users/stefan/Desktop/repos/wearedevpunks-skills diff --check
• rg -n "Layer Classifier|Dependency Injection|Public Boundaries|Validation Prompts" /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/backend/backend-domain-structure
• bun run sync:skills
• diff -qr /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/backend/backend-domain-structure apps/cli/skills/agnostic/backend/backend-domain-structure
• diff -qr apps/cli/skills/agnostic/backend/backend-domain-structure .agents/skills/backend-domain-structure
• bun run --cwd apps/cli test src/content/content.test.ts
• git diff --check

Risks And Mitigations

• Risk: Existing dirty shared-source edits belong to another worker. Mitigation: inspect source git status and diff before editing; preserve unrelated changes.
• Risk: bun run sync:skills ignores unpublished local edits. Mitigation: commit and push shared source before syncing Harness.
• Risk: Active .agents mirror remains stale after CLI sync. Mitigation: explicitly diff active mirror against CLI bundle and align or record why not.
• Risk: Skill becomes too specific to Harness. Mitigation: reject project paths/names and keep examples generic.
• Risk: Compatibility aliases linger after future refactors. Mitigation: include stale symbol and alias search in validation prompts.

Unresolved Questions

None.