TASKS-v0.9.0-docs.md — Doc structure redesign + PROJECT-INSTRUCTIONS rewrite

Rules for Code

Work on branch: feature/v0.9.0-docs
Read CLAUDE.md and STANDARDS.md before starting
Read sessions/CURRENT.md for project state
All merges require PRs to dev
Code never touches staging or main
Follow Conventional Commits format

Context

This task set redesigns the docs/ folder structure for enterprise scale, replaces DECISIONS.md with ADR-style numbered decisions, rewrites PROJECT-INSTRUCTIONS.md with a custom/standard split, and adds new config fields. These tasks merge to dev alongside the existing v0.9.0 work.

Definition of done (per task)

File edited or created correctly
npm run build passes
Committed with correct message format
No hardcoded personal values in templates

Task 1 — Replace DECISIONS.md template with decisions/ folder

Commit: feat: replace DECISIONS.md with ADR-style decisions folder

File: src/createFolders.ts

Add to the dirs array:

path.join(projectPath, "docs", "decisions"),

File: src/createDocs.ts

Stop copying DECISIONS.md to docs/. Remove the block that writes DECISIONS.md.

Add a block to create the first ADR as a seed file:

const adrContent = `---
number: 1
title: Tech stack selection
status: proposed
date: ${new Date().toISOString().split("T")[0]}
superseded_by: null
---

# ADR-0001: Tech stack selection

## Context
Tech stack defined during project discovery.

## Decision
[To be filled during discovery]

## Consequences
All code, tooling, and dependencies follow from this choice.
`;
fs.writeFileSync(path.join(docsDir, "decisions", "0001-tech-stack.md"), adrContent);

File: templates/DECISIONS.md

Add deprecation notice at top:

<!-- DEPRECATED: Replaced by docs/decisions/ folder with individual ADR files in v0.9.0 -->

Keep the file for migration compatibility.

Create: templates/adr-template.md

---
number: [NUMBER]
title: [SHORT TITLE]
status: proposed
date: [DATE]
superseded_by: null
---

# ADR-[NUMBER]: [SHORT TITLE]

## Context
[What forces are at play? What is the problem or requirement?]

## Decision
[What was decided and why]

## Alternatives considered
[What else was evaluated]

## Consequences
[What becomes easier? What becomes harder? What are the tradeoffs?]

Update: printDryRun() in src/index.ts — replace DECISIONS.md with decisions/ folder in the tree output.

Definition of done: New projects get docs/decisions/ with seed ADR and template. DECISIONS.md no longer generated. Build passes.

Task 2 — Remove project-level SPEC.md and TASKS.md from create

Commit: refactor: remove project-level SPEC.md and TASKS.md from sc create

File: src/createDocs.ts

Remove "SPEC.md" and "TASKS.md" from the TEMPLATE_FILES array. These docs now only exist per-feature in docs/features/[name]/.

Keep the template files in templates/ — they’re still used when Chat produces feature-level docs that get copied into docs/features/[name]/.

File: src/index.ts — update printDryRun():

Remove SPEC.md and TASKS.md from the docs/ tree
Add a comment line: │ ├── decisions/ ← ADR-style decision records
Update features/ line: │ ├── features/ ← per-module docs (created during discovery)

Definition of done: sc create no longer generates SPEC.md or TASKS.md at project root docs/. Build passes.

Task 3 — Update SCHEMA.md template for multi-database support

Commit: docs: update SCHEMA.md template for multi-database and module relationships

File: templates/SCHEMA.md

Replace entire contents with:

# SCHEMA.md — [project-name]

## Databases
_List all databases used by this project._

| Database | Engine | Purpose | Modules |
|----------|--------|---------|---------|
| | | | |

## Cross-module relationships
_How do tables in different modules relate to each other?_

## Shared tables
_Tables used by multiple modules. Define ownership and access patterns._

## Module-specific schemas
Each module maintains its own SCHEMA.md in docs/features/[module]/.
Project-level SCHEMA.md documents relationships between modules only.

## Notes
_Migration strategy, naming conventions, indexing rules._

Definition of done: Template reflects multi-database, multi-module reality. Build passes.

Task 4 — Add operatorNotes config field

Commit: feat: add operatorNotes field to config and sc init

File: src/config.ts

Add to ScaffolderConfig interface:

operatorNotes: string;

Add to DEFAULT_CONFIG:

operatorNotes: "",

File: src/sc.ts

In handleInit(), add after operatorDescription prompt:

const operatorNotes = await prompt("Any notes for Chat AI? (e.g. 'I have brain fog, prompt everything' or 'I'm not technical, explain everything')", "");

Add to fields array:

["operatorNotes", operatorNotes],

File: src/createDocs.ts

In replaceAiNames(), add:

const operatorNotes = globalConfig.operatorNotes || "";
content = content.replace(/\[OPERATOR_NOTES\]/g, operatorNotes);

Definition of done: operatorNotes stored in config, available as placeholder. Build passes.

Task 5 — Rewrite PROJECT-INSTRUCTIONS.md template with custom/standard split

Commit: refactor: rewrite PROJECT-INSTRUCTIONS.md with custom and standard sections

File: templates/PROJECT-INSTRUCTIONS.md

Replace the entire file. The new structure has two clearly marked sections:

# PROJECT-INSTRUCTIONS.md — [CHAT_AI_NAME] system instructions

<!-- ═══════════════════════════════════════════════════════ -->
<!-- CUSTOM SECTION — Edit freely. Preserved during updates. -->
<!-- ═══════════════════════════════════════════════════════ -->

## Custom — Your settings

**AI names:** [CHAT_AI_NAME] (Chat) / [CODE_AI_NAME] (Code)
**Operator:** [OPERATOR_DESCRIPTION]
**Notes:** [OPERATOR_NOTES]

### Personality overrides
_Add any personality or behavior preferences here. Examples:_
_- "Be direct, skip pleasantries"_
_- "I have brain fog from medications — never assume I remember anything"_
_- "I'm not technical, explain everything"_
_- "I know React but not databases"_

### Environment
- Drive: [DEFAULT_DRIVE]
- GitHub: [GITHUB_USERNAME]
- OS: [ENVIRONMENT]

<!-- ═══════════════════════════════════════════════════════ -->
<!-- STANDARD SECTION — Do not edit below this line.        -->
<!-- Replace this section when updating scaffolder version. -->
<!-- ═══════════════════════════════════════════════════════ -->

## Standard — v0.9.0

### Your role
- Planner, architect, and documentation writer
- [CODE_AI_NAME] is the builder — it executes, never plans
- You never write production code directly
- Nothing gets built without explicit operator confirmation

### Core rules
1. Never produce any document without operator confirmation
2. Ask 2-4 questions at a time, wait for answers
3. Number all questions so operator can number responses
4. Always prompt the next step — never wait for operator to ask
5. Flag scope creep immediately — capture in _ideas
6. Set time expectations at start of every discovery session
7. Confirm before generating — no surprises
8. No technical debt — ever

### Discovery
Discovery is layered. See the Discovery skill doc for the full process.

**Layer 1 — Project discovery (one session):** What is it, who is it for, what scale. Enough to run `sc create`.

**Layer 2 — Module/feature discovery (ongoing):** Each module gets its own discovery before planning. Produces docs in docs/features/[module]/.

**STOP rule:** Do not produce any document until the operator explicitly says "go", "proceed", "confirmed", or "yes produce it." Never bundle multiple docs. One at a time. Confirmation before each.

### Doc production sequence
Per module: DISCOVERY.md → SPEC.md → ARCHITECTURE.md → SCHEMA.md → TASKS.md
All docs go in docs/features/[module-name]/.
Project-level docs (ARCHITECTURE.md, SCHEMA.md) updated when cross-module concerns change.

### Decisions (ADR)
All architectural decisions recorded in docs/decisions/ as numbered ADR files.
- Chat produces ADRs with status: proposed
- Operator reviews and confirms → status: accepted
- Accepted ADRs are immutable — never edited
- To change a decision: create new ADR that supersedes the old one
- Enterprise tier: ADRs proposed via GitHub PR with `rfc` label for team review

### Session management
See the Session Management skill doc for full checklist.

**Starting:** Upload sessions/CURRENT.md to Project Files. Start conversation with project name and goal.

**Ending:** Produce session log file. Give operator one copy command. Suggest AR name.

### Branch flow
- Code works on feature branches only
- Code pushes to dev only via PR
- dev → staging: operator decision, operator PR, operator merge
- staging → main: operator decision, operator PR, operator merge
- Code never touches staging or main

### Workflow by scale tier

**Hobby:** feature → dev → main. No staging.

**Professional:** feature → dev → staging → main.

**Enterprise:** Same as professional + required approvals, CI must pass, conversation resolution required. RFC workflow for decisions.

### Session commands quick reference

sc create “project-name” — create a new project sc build [project] — open project with Code AI sc start planning [project] — begin planning session sc end planning [project] — end session, log time sc done — end session + generate log sc exit — end session and exit Code sc status [project] — show project state sc ruleset — configure branch protection preset sc help [command|topic] — show help

### Folder structure

[project-name]/ ├── .claude/commands/, skills/, rules/ ├── .github/workflows/, ISSUE_TEMPLATE/ ├── docs/ │ ├── decisions/ ← ADR-style, numbered, immutable │ ├── features/ ← per-module docs (created during discovery) │ │ └── [module]/ │ │ ├── DISCOVERY.md, SPEC.md, ARCHITECTURE.md │ │ ├── SCHEMA.md, TASKS.md, TESTING.md │ ├── ARCHITECTURE.md ← project-level overview │ ├── SCHEMA.md ← cross-module relationships │ ├── DISCOVERY.md ← project-level, Layer 1 │ ├── PLANNING.md, API.md, TESTING.md │ ├── NAMING-CONVENTIONS.md, RETRO.md ├── sessions/CURRENT.md, logs/ ├── src/ ├── CLAUDE.md, STANDARDS.md, START-HERE.md ├── STATUS.md, TIME-LOG.md, README.md, CHANGELOG.md

Note: This is a large file replacement. Read the existing file first, ensure nothing critical from the old version is lost. The standard section should be comprehensive enough that Chat can operate from it alone, with skill docs providing deeper guidance when needed.

Definition of done: Template has clear custom/standard split. All placeholders work. No hardcoded values. Build passes.

Task 6 — Update CLAUDE.md template for new doc structure

Commit: docs: update CLAUDE.md template for per-feature docs and ADR

File: templates/CLAUDE.md

Update the folder structure section to match the new layout:

Replace DECISIONS.md with decisions/ folder
Remove SPEC.md and TASKS.md from project-level docs/ listing
Add features/ with module subfolder example
Add note: “SPEC.md and TASKS.md exist per-feature only, in docs/features/[module]/”

Update Rules for Code:

Add: “Never modify files in docs/decisions/ that have status: accepted”
Change rule 7 from “Never add features not listed in docs/TASKS.md” to “Never add features not listed in the current module’s docs/features/[module]/TASKS.md”

Also update the scaffolder’s own CLAUDE.md at project root with the same doc structure changes.

Definition of done: Both CLAUDE.md files reflect new doc structure. Build passes.

Task 7 — Update STANDARDS.md template for ADR and per-feature docs

Commit: docs: update STANDARDS.md for ADR lifecycle and per-feature docs

File: templates/STANDARDS.md

Replace the “Decisions log” section with:

## Architecture Decision Records (ADR)
All architectural decisions are recorded in docs/decisions/ as numbered markdown files.

Naming: 0001-short-description.md (zero-padded, sequential)

Lifecycle:
- proposed — under discussion, not yet confirmed
- accepted — confirmed and immutable, do not edit
- rejected — considered but not adopted, kept for history
- superseded — replaced by a newer ADR (reference the new one)

Once accepted, an ADR is locked. To change a decision, create a new ADR that supersedes it. The only edit allowed on an accepted ADR is adding a superseded_by reference.

Template: templates/adr-template.md

Enterprise tier: proposed ADRs are submitted as GitHub PRs with the `rfc` label for team review before acceptance.

Add a “Per-feature documentation” section:

## Per-feature documentation
Each feature or module gets its own folder in docs/features/[module-name]/ containing:
- DISCOVERY.md — Layer 2 discovery for this module
- SPEC.md — what it does, user stories, acceptance criteria
- ARCHITECTURE.md — how it's built
- SCHEMA.md — module-specific database tables
- TASKS.md — ordered build list
- TESTING.md — test plan for this module

Feature folders are created during Layer 2 discovery, not at project creation.
Project-level docs (ARCHITECTURE.md, SCHEMA.md) document cross-module concerns only.

Definition of done: STANDARDS.md documents ADR lifecycle and per-feature structure. Build passes.

Task 8 — Update migration, dry run, and version references

Commit: chore: update migration, dry run, and docs for doc structure changes

Update versions.json to add doc structure changes to v0.9.0 changes array:

“Per-feature docs structure (docs/features/[module]/)”
“ADR-style decisions folder replaces DECISIONS.md”
“PROJECT-INSTRUCTIONS.md rewritten with custom/standard split”
“operatorNotes config field”
“SCHEMA.md updated for multi-database support”

Update the v0.8.1-to-v0.9.0 migration in src/migrations/: Add to filesAdded:

"docs/decisions/0001-tech-stack.md",

Add to filesChanged:

"CLAUDE.md",
"STANDARDS.md",
"docs/SCHEMA.md",

Add to filesRemoved:

"docs/DECISIONS.md",
"docs/SPEC.md",
"docs/TASKS.md",

Update instructions to mention the doc structure changes.

Update CHANGELOG.md with the doc structure entries.

Definition of done: Migration, versions, changelog all reflect doc structure changes. Build passes.

Task 9 — Update scaffolder’s own project docs for new structure

Commit: docs: update scaffolder project docs for new structure

Create docs/decisions/ folder in scaffolder project
Move content from docs/DECISIONS.md (if any meaningful entries exist) into individual ADR files in docs/decisions/
If no meaningful entries, just create the folder with a .gitkeep
Update docs/ARCHITECTURE.md to reflect new doc structure
Update docs/SPEC.md to note that per-feature docs are the standard (scaffolder itself doesn’t use features/ since it’s a single-module project)
Update STATUS.md with current version info

Definition of done: Scaffolder’s own docs match the structure it generates. Build passes.