TASKS.md — scaffolder v0.8.0 skills, slash commands, and plugins

Rules for Code

Always work on a feature branch, never directly on dev or main
Read CLAUDE.md and STANDARDS.md before starting any work
Read sessions/CURRENT.md for project state
Complete each task fully before moving to the next
Do not add features not listed here
Follow Conventional Commits format on every commit
Update sessions/CURRENT.md at the end of every session
All merges require PRs
Create GitHub milestone and issues before starting work

Branch

Create one branch for all tasks: feature/v0.8.0-skills All tasks committed to that branch. Final PR: feature/v0.8.0-skills → dev (PR) → main (PR)

Version target

v0.8.0

Context

This release adds Claude Code skills and slash commands to the scaffolder — both for the scaffolder’s own development and as templates copied into new projects. Skills provide Code with guided workflows for session management and planning. Slash commands give operators quick access to /sc functionality from within Code sessions.

Reference: MASTER-PLAN-v0.7.0-2026-03-15.md in docs/ for architectural context.

Pre-work

Before starting Task 1:

Create GitHub milestone: v0.8.0
Create GitHub issues for each task (Tasks 1-12)
Confirm all issues created and milestone assigned

Definition of done

A task is only complete when:

File created or edited correctly
No hardcoded personal values
npm run build passes (for source code tasks)
Committed with correct message format
Corresponding GitHub issue referenced in commit

Release checklist (before dev → main PR)

Build order

SECTION A — Slash commands for scaffolder project

Task 1 — Create scaffolder’s own .claude/commands/ slash commands

Branch: feature/v0.8.0-skills Commit: feat: add /sc slash commands to scaffolder .claude/commands/

Create the following files in .claude/commands/ at the scaffolder project root. Each file is a markdown file that Code reads when the operator types the command.

.claude/commands/sc-start.md:

---
description: "Start a session timer for this project"
---
Run `sc start $ARGUMENTS` in the terminal. If no arguments provided, prompt the operator for session type (planning/build/testing) and project name.

After starting, confirm the session type and project to the operator.

.claude/commands/sc-end.md:

---
description: "End the active session, log time, update sessions/CURRENT.md"
---
Run `sc end` in the terminal.

After the command completes, also:
1. Update sessions/CURRENT.md with what was completed this session
2. Commit the updated sessions/CURRENT.md
3. Report the session duration and updated state to the operator

.claude/commands/sc-exit.md:

---
description: "End session and exit Claude Code"
---
Run `sc exit` in the terminal. This ends any active session, logs time, updates sessions/CURRENT.md, and exits.

Before running, ensure all work is committed on the current branch.

.claude/commands/sc-status.md:

---
description: "Show current project status"
---
Run `sc status $ARGUMENTS` in the terminal and report the output to the operator.

Also read sessions/CURRENT.md and summarize: current version, active branch, what was done last session, and next steps.

.claude/commands/sc-done.md:

---
description: "End session, generate session log, run full checklist"
---
Run `sc done` in the terminal.

Before running, ensure:
1. All work is committed on the current branch
2. sessions/CURRENT.md is updated with what was completed
3. Any open PRs are noted

After the command completes, report the session log filename and location to the operator.

.claude/commands/sc-create.md:

---
description: "Create a new project with full scaffolding"
---
Run `sc create $ARGUMENTS` in the terminal. This creates a new project with the full scaffolder structure.

If no project name is provided, prompt the operator for one.

.claude/commands/sc-queue.md:

---
description: "View or manage the task queue"
---
Run `sc queue $ARGUMENTS` in the terminal.

No arguments: show open queue items.
`add "description"`: add an item.
`done [number]`: mark item complete.
`next`: show highest priority item.

.claude/commands/sc-history.md:

---
description: "Show time tracking summary for a project"
---
Run `sc history $ARGUMENTS` in the terminal and report the output.

.claude/commands/sc-log.md:

---
description: "Add a manual time entry"
---
Run `sc log $ARGUMENTS` in the terminal.

Expected format: sc log [time] [type] [project] "description"
Example: sc log 45m build scaffolder "Fixed hardcoded paths"

.claude/commands/sc-config.md:

---
description: "View or update scaffolder configuration"
---
Run `sc config $ARGUMENTS` in the terminal.

`list`: show all config values.
`get [key]`: show one value.
`set [key] [value]`: update one value.

.claude/commands/sc-help.md:

---
description: "Show scaffolder help"
---
Run `sc help $ARGUMENTS` in the terminal and report the output.

Definition of done: 11 slash command files created in scaffolder’s .claude/commands/. Each has frontmatter with description. Each invokes the corresponding sc CLI command.

Task 2 — Create slash command templates for new projects

Branch: feature/v0.8.0-skills Commit: feat: add /sc slash command templates for new projects

Create a templates/claude-commands/ directory with the same 11 files from Task 1, but with one difference: remove any scaffolder-specific content. These are generic commands that work for any project.

The files should be identical to Task 1 since the sc commands are global (not project-specific).

Update src/createFolders.ts: Add to the dirs array:

path.join(projectPath, ".claude", "commands"),

Update src/createDocs.ts: Add a block to copy all command files:

// Copy slash command templates to .claude/commands/
const commandsTemplateDir = path.join(TEMPLATES_DIR, "claude-commands");
if (fs.existsSync(commandsTemplateDir)) {
  const commandFiles = fs.readdirSync(commandsTemplateDir);
  for (const file of commandFiles) {
    const content = fs.readFileSync(path.join(commandsTemplateDir, file), "utf-8");
    fs.writeFileSync(path.join(projectPath, ".claude", "commands", file), content);
  }
}

Update printDryRun() in src/index.ts: Add under .claude/:

│   ├── commands/         ← /sc slash commands

Definition of done: templates/claude-commands/ has 11 files. New projects get .claude/commands/ populated. Dry run shows commands/. Build passes.

SECTION B — Skills for scaffolder project

Task 3 — Create session-start skill

Branch: feature/v0.8.0-skills Commit: feat: add session-start skill

Create .claude/skills/session-start/SKILL.md:

---
name: session-start
description: "Use this skill when starting a new coding session. Reads project state, checks git status, and reports readiness."
---

# Session Start

When starting a new session on this project:

1. Read `sessions/CURRENT.md` and summarize:
   - Current version
   - Active branch
   - What was done last session
   - What is next

2. Run `git status` and report:
   - Current branch
   - Any uncommitted changes
   - Whether the branch is up to date with remote

3. Check for open PRs:
   - Run `gh pr list --state open` and report any

4. Check for open issues:
   - Run `gh issue list --state open --limit 5` and report

5. Report all findings to the operator and ask:
   "Ready to start. What are we working on this session?"

Do NOT start any work until the operator confirms the goal.

Also create the same file in templates/claude-skills/session-start/SKILL.md for new projects.

Definition of done: Skill file created in both scaffolder and templates. Follows SKILL.md format with frontmatter.

Task 4 — Create session-end skill

Branch: feature/v0.8.0-skills Commit: feat: add session-end skill

Create .claude/skills/session-end/SKILL.md:

---
name: session-end
description: "Use this skill when ending a coding session. Updates project state, writes session log, and prepares for handoff."
---

# Session End

When ending a session on this project:

1. Ensure all work is committed on the current branch:
   - Run `git status`
   - If uncommitted changes exist, commit them with an appropriate message
   - Push the branch

2. Update `sessions/CURRENT.md`:
   - Current state: describe what the project looks like right now
   - Version: current version from .scaffolder
   - Active branch: which branch we're on
   - What was done last session: summarize this session's work
   - What is in progress: anything started but not finished
   - What is not started: known upcoming work
   - What is working / not working: current build state
   - Decisions made: any decisions from this session
   - Next steps: what should happen next
   - Watch out for: any risks or gotchas

3. Write a session log to `sessions/logs/`:
   - Filename format: v[XX].[XX].[XX]-[YYYY]-[MM]-[DD]-[HHMM]-code-[operator].md
   - Include frontmatter: version, date, time, type (code), operator, duration, project
   - Include: what was completed, decisions made, current state, next steps

4. Commit sessions/CURRENT.md and the session log

5. Report to operator:
   - Summary of what was done
   - Any open PRs that need review
   - Suggested next steps
   - Remind: "Upload updated sessions/CURRENT.md to your Chat Project Files"

Also create in templates/claude-skills/session-end/SKILL.md.

Definition of done: Skill created in both locations. Comprehensive session closing workflow.

Task 5 — Create plan-mode-reminder skill

Branch: feature/v0.8.0-skills Commit: feat: add plan-mode-reminder skill

Create .claude/skills/plan-mode-reminder/SKILL.md:

---
name: plan-mode-reminder
description: "Suggests plan mode when tasks are complex. Activates when a task touches 3+ files or adds new functionality."
---

# Plan Mode Reminder

Before starting any task, evaluate its complexity:

**Suggest plan mode if the task:**
- Touches 3 or more files
- Adds new functionality (not just fixing/updating)
- Changes architecture or folder structure
- Introduces a new dependency
- Modifies database schema
- Changes API contracts

**Skip plan mode if the task:**
- Is a single-file bug fix
- Is a documentation-only change
- Is a version bump or changelog update
- Is a rename or move operation

When suggesting plan mode, say:
"This task looks complex — it touches [X files / adds new functionality / etc]. I'd recommend entering plan mode first so we can align on the approach. Want me to plan before coding?"

If the operator says yes, create a plan covering:
- Files to be changed
- Approach and sequence
- Risks or edge cases
- Estimated scope

If the operator says no, proceed but note that plan mode was offered.

Also create in templates/claude-skills/plan-mode-reminder/SKILL.md.

Definition of done: Skill created in both locations. Clear triggers and skip conditions.

Task 6 — Copy skills into new projects via createDocs

Branch: feature/v0.8.0-skills Commit: feat: copy skills templates into new projects

Update src/createFolders.ts: Add skills directories to the dirs array:

path.join(projectPath, ".claude", "skills"),
path.join(projectPath, ".claude", "skills", "session-start"),
path.join(projectPath, ".claude", "skills", "session-end"),
path.join(projectPath, ".claude", "skills", "plan-mode-reminder"),

Update src/createDocs.ts: Add a block to copy skill files:

// Copy skill templates to .claude/skills/
const skillsTemplateDir = path.join(TEMPLATES_DIR, "claude-skills");
if (fs.existsSync(skillsTemplateDir)) {
  const skillFolders = fs.readdirSync(skillsTemplateDir, { withFileTypes: true })
    .filter(d => d.isDirectory());
  for (const folder of skillFolders) {
    const skillDir = path.join(projectPath, ".claude", "skills", folder.name);
    fs.mkdirSync(skillDir, { recursive: true });
    const skillFile = path.join(skillsTemplateDir, folder.name, "SKILL.md");
    if (fs.existsSync(skillFile)) {
      fs.copyFileSync(skillFile, path.join(skillDir, "SKILL.md"));
    }
  }
}

Update printDryRun() in src/index.ts: Update .claude/ section:

├── .claude/
│   ├── commands/             ← /sc slash commands
│   ├── rules/
│   ├── settings.local.json
│   └── skills/
│       ├── session-start/
│       ├── session-end/
│       └── plan-mode-reminder/

Definition of done: New projects get all three skills and all slash commands. Dry run output updated. Build passes.

SECTION C — Documentation and plugin guidance

Task 7 — Document the two-AI architecture in README

Branch: feature/v0.8.0-skills Commit: docs: add two-AI architecture explanation to README

File: README.md

Add a new section after “Why” and before “What you get”:

## How it works

Scaffolder coordinates two AI systems to manage your projects:

**Chat AI** (Claude Chat) is your architect and planner. It runs discovery, produces specs, and plans every feature before code is written. It works through a Claude Project with shared instructions and knowledge.

**Code AI** (Claude Code) is your builder. It reads the planning docs and builds exactly what's specified. It has skills and slash commands that automate session management, planning workflows, and project state tracking.

**You** are the operator. You make decisions, review plans, merge PRs, and direct both AIs. Neither does anything without your approval.

The two AIs communicate through shared files:
- `sessions/CURRENT.md` — project state that both AIs read and update
- `sessions/logs/` — immutable session records from both Chat and Code
- `docs/` — planning artifacts produced by Chat, consumed by Code
- `CLAUDE.md` — standing instructions Code reads automatically every session

Definition of done: README explains the architecture clearly for new users.

Task 8 — Document skills and slash commands in docs/COMMANDS.md

Branch: feature/v0.8.0-skills Commit: docs: add skills and slash commands documentation to COMMANDS.md

File: docs/COMMANDS.md

Add two new sections:

Slash commands (after the existing command sections):

## Slash commands

Slash commands are available inside Claude Code sessions. Type the command name and Code will execute it.

All /sc slash commands invoke the corresponding `sc` CLI command and handle session context automatically.

Available commands:
- `/sc-start` — start a session timer
- `/sc-end` — end session, update CURRENT.md
- `/sc-exit` — end session and exit Claude Code
- `/sc-done` — full session close with log generation
- `/sc-status` — show project status
- `/sc-create` — create a new project
- `/sc-queue` — manage task queue
- `/sc-history` — show time summary
- `/sc-log` — add manual time entry
- `/sc-config` — view/update configuration
- `/sc-help` — show help

Slash commands live in `.claude/commands/` and are created automatically by `sc create`.

Skills section:

## Skills

Skills are automatic workflows that Code uses when relevant. They don't need to be invoked — Code detects when to use them.

Built-in skills:
- **session-start** — reads project state, checks git, reports readiness at session start
- **session-end** — updates CURRENT.md, writes session log, commits at session end
- **plan-mode-reminder** — suggests plan mode for complex tasks (3+ files, new functionality)

Skills live in `.claude/skills/` and are created automatically by `sc create`.

### Creating custom skills

Create a new folder in `.claude/skills/` with a `SKILL.md` file:

.claude/skills/my-skill/ └── SKILL.md

The SKILL.md needs frontmatter with name and description:

```yaml
---
name: my-skill
description: "When to use this skill"
---

# Instructions for Code
...

Code will automatically discover and use skills when the description matches the current task.

**Definition of done:** Both sections documented clearly.

---

### Task 9 — Document plugin installation in docs/CUSTOMIZE.md

**Branch:** feature/v0.8.0-skills
**Commit:** `docs: add plugin installation guidance to CUSTOMIZE.md`

**File:** `docs/CUSTOMIZE.md`

Add a new section:

```markdown
## Recommended plugins

These optional plugins enhance Claude Code's capabilities. Install them from within a Claude Code session:

### claude-md-management
Audits CLAUDE.md quality, captures session learnings, keeps project memory current.
```bash
/plugin marketplace add anthropics/claude-plugins-official
/plugin install claude-md-management@anthropics/claude-plugins-official

pr-review-toolkit

Comprehensive PR review with specialized agents for code quality, tests, errors, and types.

/plugin marketplace add anthropics/claude-plugins-official
/plugin install pr-review-toolkit@anthropics/claude-plugins-official

skill-creator

Helps create new custom skills with proper structure and frontmatter.

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@anthropics/claude-plugins-official

Note: Plugin installation is per-user, not per-project. Install once and they’re available in all your Claude Code sessions.

**Definition of done:** Plugin install instructions documented. No cost claims.

---

### Task 10 — Update CLAUDE.md template to reference skills and commands

**Branch:** feature/v0.8.0-skills
**Commit:** `docs: update CLAUDE.md template to reference skills and slash commands`

**File:** `templates/CLAUDE.md`

Add a section after "Session management":

```markdown
## Skills and commands
This project includes built-in skills and slash commands in `.claude/`.

**Skills** (automatic — used when relevant):
- `session-start` — reads project state at session start
- `session-end` — updates CURRENT.md and writes session log at session end
- `plan-mode-reminder` — suggests plan mode for complex tasks

**Slash commands** (manual — type to invoke):
- `/sc-start`, `/sc-end`, `/sc-exit`, `/sc-done` — session management
- `/sc-status`, `/sc-queue`, `/sc-history` — project info
- `/sc-create`, `/sc-config`, `/sc-log`, `/sc-help` — utilities

Use skills automatically. Use slash commands when you need direct control.

Also update the scaffolder’s own CLAUDE.md at project root with the same section (customized for scaffolder).

Definition of done: Both CLAUDE.md files reference available skills and commands.

Task 11 — Update dry run and ARCHITECTURE.md

Branch: feature/v0.8.0-skills Commit: docs: update ARCHITECTURE.md and dry run for skills and commands

File: docs/ARCHITECTURE.md — add skills/ and commands/ to the file structure diagram. Add a “Skills and commands” section explaining the architecture.

File: src/index.ts — verify printDryRun() shows the skills and commands directories (should be done in Task 6, but verify).

Definition of done: Architecture docs reflect skills and commands.

SECTION D — Version bump and release

Task 12 — Version bump, CHANGELOG, migration, and PR

Branch: feature/v0.8.0-skills Commit: chore: bump version to 0.8.0 Commit: docs: update CHANGELOG for v0.8.0

Bump package.json to 0.8.0
Update versions.json (latest: “0.8.0”, add entry)
Update CHANGELOG.md:

## [0.8.0] — 2026-03-15
### Added
- feat: 11 /sc slash commands in .claude/commands/ for all projects
- feat: session-start skill — automatic project state reporting
- feat: session-end skill — automatic CURRENT.md update and session logging
- feat: plan-mode-reminder skill — suggests plan mode for complex tasks
- feat: skills and commands copied to new projects via sc create
- docs: two-AI architecture explanation in README
- docs: skills and slash commands documentation in COMMANDS.md
- docs: plugin installation guidance in CUSTOMIZE.md

### Changed
- refactor: CLAUDE.md template updated to reference skills and commands
- refactor: dry run output includes .claude/commands/ and .claude/skills/
- refactor: ARCHITECTURE.md updated with skills and commands

Update README badge, STATUS.md
Create migration src/migrations/v0.7.1-to-v0.8.0.ts:

export const migration = {
  fromVersion: "0.7.1",
  toVersion: "0.8.0",
  breaking: false,
  filesAdded: [
    ".claude/commands/sc-start.md",
    ".claude/commands/sc-end.md",
    ".claude/commands/sc-exit.md",
    ".claude/commands/sc-done.md",
    ".claude/commands/sc-status.md",
    ".claude/commands/sc-create.md",
    ".claude/commands/sc-queue.md",
    ".claude/commands/sc-history.md",
    ".claude/commands/sc-log.md",
    ".claude/commands/sc-config.md",
    ".claude/commands/sc-help.md",
    ".claude/skills/session-start/SKILL.md",
    ".claude/skills/session-end/SKILL.md",
    ".claude/skills/plan-mode-reminder/SKILL.md",
  ],
  filesChanged: [
    "CLAUDE.md",
  ],
  filesRemoved: [],
  instructions: "New skills and slash commands added. Optional plugins available — see docs/CUSTOMIZE.md.",
};

PR: feature → dev (PR)
Merge dev
Verify: build passes, /sc-help works in Code, skills detected
PR: dev → main
Report PR to operator
After merge: tag v0.8.0
Update sessions/CURRENT.md
Push everything

Definition of done: v0.8.0 tagged. Skills and commands functional. All docs updated. Build clean.