Spec and Dev Workflow

Spec and Dev Workflow

Mumcord is built spec first. Two project skills for Claude Code drive this, and they live in the repository under .claude/skills/:

Skill	Purpose	Output
/spec	Turn an idea or roadmap epic into a written specification through round-based questions	specs/{nr}-{name}-brainstorming.md, specs/{nr}-{name}-specification.md and a commit
/dev	Build a finished specification, verify it in the running client, write a report	Code, specs/{nr}-{name}-tasks.md (task list), specs/{nr}-{name}-implementation.md (report)

Both skills are started by hand only (they never trigger on their own). The whole project assumes a non-technical product owner: technology choices come with a clear recommendation, explained in plain language. All documents are in English.

When to use which

• New epic or feature, or an existing spec needs a revision: /spec.
• A specification exists and you want it implemented: /dev.
• Only a brainstorming file exists: finish it with /spec first. /dev refuses to start without a specification.
• Small bug fixes and tweaks do not need either; follow the normal rules in Development.

/spec

Invoke:

/spec <epic number or feature name or description>

Examples: /spec 2, /spec "mute sounds per channel". With no argument it lists roadmap epics and existing specs and asks which one you want.

Rules the skill follows:

• One round at a time. It writes one round of questions, tells you it is ready and stops. It never answers for you.
• Questions live only in the brainstorming file (specs/{nr}-{name}-brainstorming.md), not in chat. Chat replies stay short.
• Append only. Existing questions, answers and notes are never changed. Corrections and follow-ups become new questions in the next round, so the file has no status markers.
• Pure client. It never offers options that need anything on the server side.
• MVP scope. Nice-to-haves are offered only as clearly labelled "later" options.

The brainstorming file

Each question has an ID like Q2.3 (round 2, question 3; IDs are never reused). Options use checkboxes:

• ◉ single choice: exactly one [x]. Move the x to change your answer.
• ☑ multiple choice: tick as many as you like.
• ⭐ marks the recommended option, which is already preselected. If you agree, change nothing.
• Every question ends with a ✍️ Note: line for free text: questions back, edge cases, or "not sure, explain this to me". An explanation request is answered in the next round under "Follow-ups & explanations".

Typical rounds: functionality and scope, UI/UX (with ASCII wireframes), audio and network, technology and platforms, data/state model and open points. Settled topics from earlier specs are not asked again.

You edit the file directly (checkboxes and notes), save it, and tell Claude Code the round is answered. The next round then starts.

From answers to specification

When the last round is answered, the skill appends a ## Closing note and writes specs/{nr}-{name}-specification.md from the checked boxes and notes (a later answer overrides an earlier one). The structure is fixed:

1. Goal and context, 2. Scope (in scope / out of scope), 3. Roles and permissions, 4. Functional requirements with IDs FR-{N}.{n}, 5. UI and UX, 6. Audio and network, 7. Data and state model, 8. Technology and architecture, 9. Non-functional requirements, 10. Build, packaging and release, 11. Acceptance criteria AC-{N}.{n}, 12. Decision log (referencing question IDs like Q2.3), 13. Open points and risks, 14. Impact on the roadmap.

Each acceptance criterion is a concrete flow (starting point, action, expected result) that can be verified in the running client against a local test server. For example, AC-1.5 in the Epic 1 spec: connect to a test server with a self-signed certificate, accept the fingerprint, then replace the server certificate and check that the reconnect is blocked with a warning.

Finally the skill commits the brainstorming and specification files (only those, never git add -A) with a message like docs(spec): Epic 2 - channel tree & chat specification, and does not push. If an existing spec needs changes, /spec appends an Addendum round and later makes a new commit.

/dev

Invoke:

/dev <spec number | name | path> [--no-team]

Examples: /dev 1, /dev 01-foundation, /dev 1 --no-team. With no identifier it lists the specs and asks. If specs/{nr}-{name}-implementation.md already exists, it resumes from the existing report and task list.

Phases

Phase	What happens
A. Analysis and breakdown	Spec, CLAUDE.md, earlier specs and code are read. Blocking questions go to you in plain language, with a recommended answer. A task list is created with dependencies, file ownership and a simple or complex rating per task.
B. Build	Tasks are implemented in dependency order, with tests alongside.
C. Verification	Tests, type checks and linters pass, and every AC-... is checked in the running client against a local Mumble test server (plus a second client or bot where needed). Failures become fix tasks, then verification runs again.
D. Wrap-up	The implementation report is written and you get a short final message.

A task is complex when it touches more than about three files, adds a module, data format or dependency, touches the audio pipeline or real-time behaviour, the protocol, TLS, security or privacy, platform-specific code, packaging or CI, or needs an architecture decision. Complex tasks get a short written plan before any code is touched.

The task list

All work lives in a task list: nothing is built without a task, a task is completed only when done and verified, and newly found work becomes a new task. If Claude Code's task tools are unavailable, the list is kept in specs/{nr}-{name}-tasks.md: one table row per task with ID, title, status (open, in progress, done, blocked), owner, dependencies, complexity and covered AC-... and files. See specs/01-foundation-tasks.md for a real example. Only the lead edits this file.

Team mode (default)

The main session becomes a team lead that only coordinates. It delegates reading, coding, running tests and writing the report, and keeps its own context free.

• One task, one fresh agent. Each task (analysis, build step, fix, verification, report) goes to its own newly started agent with a short, self-contained prompt. The agent sends one final report of at most 10 lines and then ends. Follow-up work goes to a new agent. Agents never talk to each other; everything goes through the lead.
• Parallel where safe. Independent tasks run at the same time, but no two running agents edit the same files, and parallel QA agents use separate test-server ports.
• Plan approval for complex tasks. The agent explores read-only, sends a plan (15 lines or fewer), and edits files only after the lead replies APPROVED.
• Independent verification. The agent that verifies a task is never the one that built it. It reports per criterion: AC-1.3 passed, needs a manual listening check, or failed with a symptom.
• Smallest suitable model per agent to save cost.
• Team mode needs agent teams enabled (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1). Without it, use --no-team.

--no-team runs the same phases in one session. Broad searches and long test runs still go to subagents, and verification prefers a subagent that did not write the code.

Verification

"Done" means verified in the running client, not only green tests. Use the local servers from testenv/ (Development), the mumcord-bot for a second participant, netsim for bad networks, and the E2E suite (Testing). Never use public or third-party servers. Audio that cannot be judged automatically (how it sounds) is checked as far as possible by levels, packets and latency numbers and then flagged for a manual listening check.

Implementation report

A fresh agent writes specs/{nr}-{name}-implementation.md: result in one sentence, an acceptance-criteria table (passed, listening check pending, or failed, with evidence), "try it yourself" steps, completed tasks, deviations from the spec, open points and technical notes. Re-runs append a Run {n} section instead of rewriting.

Commit rules

• /dev never commits, pushes, releases, signs with real keys or touches public servers without your explicit approval. At the end it asks whether to commit.
• Commits are small and focused Conventional Commits, staged by file (never git add -A), on a branch rather than the default branch.
• Secrets never go into the repository.
• No AI attribution in commit messages or pull requests.

Short end-to-end example

1. You want multi-server read-along. Run /spec 2.
2. Claude Code reads the roadmap and earlier specs, creates specs/02-multi-server-read-along-brainstorming.md with round 1 (functionality and scope) and stops.
3. You open the file, accept the preselected ⭐ options, change one checkbox, and write a ✍️ Note: asking for an explanation of one term. You tell Claude Code the round is answered.
4. Round 2 starts with a "Follow-ups & explanations" section answering your note. You repeat until the last round.
5. The skill writes specs/02-multi-server-read-along-specification.md with FR-2.x requirements and AC-2.x criteria, and commits both files.
6. Run /dev 2. The lead delegates analysis, asks you any blocking questions, and creates tasks.
7. Fresh agents build the tasks (complex ones wait for plan approval), then separate QA agents check every AC-2.x against the local test servers.
8. A report agent writes specs/02-multi-server-read-along-implementation.md. You get a pass/fail list per criterion, steps to try it yourself, and the question whether to commit.
9. You review, then ask for commits. Push and pull requests happen only on your request.