DevFoundry/specs/archive/SPEC-006-new-project-reset-skill.md

SPEC-006: New Project Reset Skill

• Status: COMPLETED
• Stack: DevFoundry process documentation (template adoption tooling)
• Target Files: .devfoundry/skills/new-project-reset.md (new), README.md, AGENTS.md

---

0. Spec Creation Checklist

• Status is DRAFT before user approval.
• Target Files are listed and checked for overlap with other active specs — specs/active/ was empty; no conflict.
• Build/test/lint commands documented — N/A, documentation-only spec.
• Database changes — none; not applicable.
• Every implementation task has a preceding test/manual-verification task and completed: timestamp space.

1. Business Context & Goal

specs/archive/ currently holds DevFoundry's own process-development history (SPEC-001–005), not any real project's history — this template has no built-in way to clear that out when it's copied to start an actual new project. The user asked for “a way to clear out the spec archive when we start a new spec.” Clarified via two direct questions: (1) this means a one-time reset run when adopting the template for a brand-new project, not a per-spec recurring action, and (2) old specs should be deleted outright, not moved to cold storage — they're DevFoundry's own internal history, not the new project's.

No other active specs existed, so there were no target-file conflicts.

2. Acceptance Criteria (Given / When / Then)

• AC-1: Given a user wants to adopt DevFoundry for a new project, when they ask for the reset, then .devfoundry/skills/new-project-reset.md gives an explicit, ordered procedure covering specs/archive/, specs/active/, specs/.spec-counter, .devfoundry/improvement-log.md, and residual project-specific facts in .devfoundry/references/. — PASS
• AC-2: Given the skill exists, when an agent might otherwise run it opportunistically, then the skill and AGENTS.md both state it only runs on explicit request, never automatically and never as part of the normal spec lifecycle. — PASS
• AC-3: Given a user is reading top-level docs, when they open README.md, then they find a pointer to this skill explaining why and when to use it. — PASS
• AC-4: Given the reset procedure risks discarding in-progress work, when specs/active/ is non-empty at reset time, then the skill instructs stopping and confirming with the user rather than silently deleting it. — PASS

3. Technical Design & Contracts

• Data Model / Schema Changes: None. Rollback is a git revert of documentation changes.
• Functions / APIs / Interfaces: None — this is a documented manual/agent-followed procedure, not executable code.
• Architecture: N/A — process documentation only.
• Error Handling Strategy: N/A. The skill's own step 2 covers the “unrecoverable if not git-tracked” risk by requiring explicit confirmation before deleting anything.

4. Implementation Plan (Atomic Steps, TDD-ordered)

• Step 1 (verification authoring): Wrote this spec's acceptance criteria, informed by the user's answers to the two clarifying questions, before drafting the skill — files: specs/active/SPEC-006-new-project-reset-skill.md — completed: 2026-08-19 23:20
• Step 2 (implementation): Added .devfoundry/skills/new-project-reset.md with the ordered reset procedure and explicit-trigger-only guardrail — files: .devfoundry/skills/new-project-reset.md — completed: 2026-08-19 23:21
• Step 3 (implementation): Added an “Adopting This Template for a New Project” section to README.md, and Collaboration Rule 6 to AGENTS.md stating the reset is separate from and never a substitute for the normal Archive step — files: README.md, AGENTS.md — completed: 2026-08-19 23:22
• Step 4 (verification): Re-read the new skill and both edited docs end-to-end to confirm every acceptance criterion is met and the skill was not itself invoked against this repo's real archive — files: listed target files — completed: 2026-08-19 23:23

5. Verification & Regression Plan

• Verify AC-1 by confirming new-project-reset.md covers all five listed items (archive, active, counter, improvement-log, references) in an explicit numbered order.
• Verify AC-2 by confirming both the skill's own header and AGENTS.md Collaboration Rule 6 state “only on explicit request.”
• Verify AC-3 by confirming README.md contains a section linking to the skill.
• Verify AC-4 by confirming skill step 4 instructs stopping and confirming rather than silently deleting a non-empty specs/active/.
• Regression check: confirmed specs/archive/SPEC-001 through SPEC-005 were not deleted by this spec — the skill was authored but deliberately not executed, since the user asked for the capability, not for it to be run yet.

6. Retrospective

Filled by the Process Improver per .devfoundry/skills/process-retrospective.md, after QA approval and before archiving.

• What worked: Asking two direct clarifying questions before writing anything (scope: one-time adoption reset vs. per-spec; disposition: delete vs. cold-storage) avoided building the wrong, more destructive mechanism — “clear the archive” had at least one plausible reading (recurring, per-spec) that would have silently destroyed audit trail on every cycle.
• Friction (rule/reference/interview gap, or none): none — the existing spec machinery handled this cleanly once scope was confirmed.
• Logged in .devfoundry/improvement-log.md: yes