Skip to content
specdacular

Team Workflow

Specdacular works with individual developers out of the box. This guide covers patterns for teams sharing a codebase where multiple developers use specdacular in the same repository.

Commit .specd/ to version control

Section titled “Commit .specd/ to version control”

The .specd/ directory is designed to live in your repository:

Terminal window
# Don't add this to .gitignore
.specd/

Specdacular auto-commits docs and state changes throughout the lifecycle. When teammates pull, they get:

  • Up-to-date codebase maps
  • Feature plans their colleagues are working on
  • Decisions made in other sessions
  • The current execution state of every task

This creates a shared planning record without any extra tooling.

Shared codebase maps

Section titled “Shared codebase maps”

Run /specd.codebase.map once and commit it. Everyone on the team benefits from the same MAP.md, PATTERNS.md, STRUCTURE.md, and CONCERNS.md.

When to refresh the map:

  • After major architectural changes
  • After onboarding a significant new library or pattern
  • When you notice the map is giving Claude stale guidance

Treat the codebase map as a team-maintained document. If a teammate’s session produces a better map, their commit updates it for everyone.

Feature ownership

Section titled “Feature ownership”

Each task in .specd/tasks/ is owned by the developer working on it. The naming convention makes ownership clear:

.specd/tasks/
├── user-auth/           # Alice is working on this
├── payment-flow/        # Bob's feature
└── api-rate-limiting/   # Both could exist in parallel

There’s no central task registry — git history shows who created what and when.

Conventions for team use

Section titled “Conventions for team use”

Name tasks after features, not developers

Section titled “Name tasks after features, not developers”

Good: user-auth, payment-flow, search-indexing Avoid: alice-auth-work, bobs-payment-task

Tasks are shared artifacts. Future teammates should understand them without knowing who created them.

Commit regularly during development

Section titled “Commit regularly during development”

Specdacular auto-commits state transitions. During execution phases, it commits after each task. This creates a dense, readable git history:

docs(user-auth): starting discuss
docs(user-auth): discuss complete
docs(user-auth): starting research
docs(user-auth): research complete
feat(user-auth): phase 1 - database schema
feat(user-auth): phase 2 - auth endpoints
Section titled “Review DECISIONS.md before starting related work”

Before implementing a feature that touches someone else’s active task, read their DECISIONS.md. It captures the rationale behind choices you might otherwise duplicate or conflict with.

Parallel feature development

Section titled “Parallel feature development”

Multiple developers can work on separate features simultaneously. The only conflict risk is if two features modify the same files. Standard git conflict resolution applies.

For features with cross-dependencies, use explicit cross-task notes in CONTEXT.md:

NOTE: This feature depends on the user-auth task's JWT middleware being complete.
Coordinate with Alice before starting phase 3.

For monorepos where features genuinely cross project boundaries, see Multi-project support.

Reviewing a teammate’s feature

Section titled “Reviewing a teammate’s feature”

If you’re asked to review work in progress:

/specd.status

This shows all in-progress features. To understand a specific task:

  • Read .specd/tasks/{name}/FEATURE.md for requirements
  • Read .specd/tasks/{name}/DECISIONS.md for rationale
  • Read .specd/tasks/{name}/ROADMAP.md for the implementation plan
  • Check STATE.md for current position

To trigger a formal code review within the specdacular flow:

/specd.toolbox feature-name

Then select Review.

Onboarding new team members

Section titled “Onboarding new team members”

New developers can get up to speed quickly:

/specd.codebase.map

Even if the map already exists, running this command in a fresh Claude Code session loads the existing maps and gives Claude the full codebase context. The new developer’s Claude session can immediately answer questions like “where does authentication happen?” and “what’s the pattern for adding a new API endpoint?”

Multi-project support

Section titled “Multi-project support”

For monorepos with multiple packages, specdacular has native multi-project support. When /specd.codebase.map detects multiple projects, it offers to enable orchestrator mode.

In orchestrator mode:

  • Features are discussed at the system level
  • Planning creates per-project roadmaps with a cross-project dependency graph
  • continue schedules execution across projects respecting dependencies
  • Contract review happens after each phase to catch cross-project deviations
/specd.continue auth-system        # Coordinates across all projects
/specd.continue auth-system api    # Target a specific sub-project

Handling stale tasks

Section titled “Handling stale tasks”

Tasks accumulate. Use /specd.status --all to see completed tasks and assess whether old in-progress tasks should be continued or abandoned.

There’s no built-in “abandon” command — if a task is no longer needed, you can delete it from .specd/tasks/ and commit the deletion.

Section titled “Related guides”