Chapter 4: Collaborating Across Product, Architecture, and Engineering
The chapter introduction explains why teams need shared specifications to onboard memoryless AI agent sessions and turn individual AI gains into team productivity.
After this chapter you will be able to
- Specifications as shared onboarding. Describe how SDD specifications help humans and agents onboard without constant guidance, distinguishing the intent they capture from what code shows.
- Shared specification authoring. Explain why separate AI adoption by individual roles is insufficient for team-wide productivity and what those roles need to contribute together.
- Specification as common control surface. Explain how a shared specification brings together each specialist’s intent to give the coding agent context for an implementation that satisfies their different points of view.
- Roles and specification phases. Describe how product specialists, architects, and engineers contribute to the Discover, Design, and Tasks phases, respectively.
- Costs of indirect authoring. Explain how routing expertise through an engineer can compromise captured intent and delay specification authoring, and why the section calls for first-hand contributions.
- Role-by-role specification handoff. Describe how product specialists, architects, and engineers contribute directly to a co-located specification, passing it from one role to the next before pull-request review.
- Sequential handoff bottleneck. Explain why passing a specification sequentially between roles becomes slow as multiple features are in flight, despite coding agents speeding up each person's contribution.
- Shared specification authoring. Describe how all roles work with an agent in one session to resolve questions and produce a specification, then send it to the Execution Harness and review the implementation together.
- Asynchronous role contributions. Explain how recurring constraints, principles, and review criteria from different roles become standing context in the Intent Harness, which the coding agent uses to guide specification authoring even when those roles are absent.
- Standing Context Versus Feature Decisions. Distinguish recurring guidance that belongs in standing context from decisions that belong in a feature specification, using the URL shortener examples.
- Flexible Standing Context Contributions. Explain how team members can add standing context as SDD adoption begins, without waiting for every role or for a feature specification.
- Product Wide Business Rules. Explain how the product specialist moves rules that apply across features into standing context, using the URL shortener examples.
- Shared Business Vocabulary. Explain how a shared vocabulary carries business meaning consistently from the product specialist through specifications, agents, and code.
- Discover Conversation Feedback. Describe the product specialist's feature-specific role in Discover and how discoveries there can improve standing context for later features.
- Architectural constraints and boundaries. Explain how the architect shapes standing context through technical constraints, bounded contexts, and interfaces between them, using the URL shortener examples.
- Relevant standing context delivery. Distinguish how the architect makes boundary-specific and cross-cutting guidance available to an agent without loading irrelevant context for every feature.
- Feature-specific design conversation. Describe how the architect’s role changes after establishing standing context, and identify the kinds of feature-specific questions left for the Design conversation.
- Engineering task list practices. Explain how engineers translate the product specialist’s requirements and the architect’s design into an executable task list, and how standing context shapes the agent’s draft for each feature.
- Evidence based task completion. Explain how task checks and optional commit checkpoints provide evidence of completion, including why branch coverage is preferred to line coverage here.
- Feature task list review. Describe what engineers review in a generated task list before the agent begins coding and when they refine it.
- Specialist security standing context. Explain how a specialist can contribute standing context alongside feature-specific details, using the URL shortener’s redirect safeguards as an example.
- Review and promotion of guidance. Describe how a security specialist checks whether standing context covers a new redirect-rules feature and handles any newly identified recurring rules.
- Evidence earned standing context. Explain why a team should begin with standing context it already knows and add new guidance only after repeated experience shows that it helps.
- Team exercise collaboration formats. Distinguish the two ways to run the group exercise: together on a shared machine or asynchronously through a Git server.
- SpecKit workflow mapping. Trace how SpecKit's commands map to standing context, Discover, Design, tasks, implementation, and verification in the SDD workflow.
- Specification-first model effort. Justify why the exercise favors strong specification context over relying on a more capable implementation model, and where greater reasoning effort is better spent.
- Feature branch collaboration trail. Explain how the SpecKit Git extension supports team collaboration and why commit permission is initially left manual.
- Just-in-time role contributions. Trace how the product specialist, architect, and engineer add standing context immediately before specification, design, and task-list authoring respectively.
- Business rules and feature scope. Distinguish product-wide business rules in the constitution from decisions that belong in this feature’s spec, using link expiration as the example.
- Architecture constraints and review. Explain how the architect’s standing constraints guide the plan and how the team checks the resulting design artifacts.
- Engineering tasks and alignment. Describe how engineering standing context shapes the task list and how analyze catches disagreements among the spec, plan, and tasks before implementation.
- Convergence and specification-first repair. Trace the implement–converge loop and explain how the team handles deviations without bypassing the specification.
- Reuse of standing context. Explain why specifying link expiration requires less setup than the first feature: the existing vocabulary, design boundaries, layering, and completion goals already give the agent enough context to help draft the specification.
- Expired link visitor experience. Explain how standing context sharpened the agent’s scope questions about link expiration, especially the question of what a visitor should see after following an expired link.
- Reusable architectural standing context. Explain why architectural patterns shared across projects should move from each project's constitution into a reusable skill, while project-specific decisions stay in the constitution.
- Standing context and human involvement. Describe how human involvement differed between the first slice and the second feature, and explain what that difference shows about standing context.
- Framework Fit With Existing Workflows. Justify adapting SDD frameworks to established delivery workflows rather than replacing those workflows with framework defaults. Explain how that integration helps stakeholders contribute to the Intent Harness.
What it builds on
- The specification is one part of the context (chapter 3) · A specification is only one part of the context available to an agent.
- The governance operating loop (chapter 3) · The idea of using feedback to improve specification governance.
- Spec-driven development workflow (chapter 2) · The SDD workflow that SpecKit's commands are mapped onto.
- Context debt and the return to manual mode (chapter 2) · The problem of losing durable context when decisions remain outside the specification.
- The direct fix trap (chapter 3) · The risk of directly fixing code while leaving its specification behind.
Section by section
Introduction
The chapter introduction explains why teams need shared specifications to onboard memoryless AI agent sessions and turn individual AI gains into team productivity.
- Agent sessions as new joiners: Explain why each agent session needs to be onboarded anew and why tribal knowledge and ad hoc conversations do not scale for that purpose.
Why it matters: This explains why an agent cannot rely on the informal onboarding a human colleague might receive. - Specifications as shared onboarding: Describe how SDD specifications help humans and agents onboard without constant guidance, distinguishing the intent they capture from what code shows.
Why it matters: Shared specifications let new sessions find both the reasons for decisions and the artifacts needed to work on the application. - Shared specification authoring: Explain why separate AI adoption by individual roles is insufficient for team-wide productivity and what those roles need to contribute together.
Why it matters: The team's gains depend on sharing each role's input where agents can use it, not just speeding up isolated tasks.
Key terms: agent session, new joiner, tribal knowledge, SDD workflow, Intent Harness, specifications, intent, specification authoring, team productivity, agent onboarding
4.1 Moving beyond solo SDD: collaboration patterns
This section explains why team-based SDD lets specialists contribute their own intent through a shared specification without requiring everyone to become a generalist.
- Specification as common control surface: Explain how a shared specification brings together each specialist’s intent to give the coding agent context for an implementation that satisfies their different points of view.
Why it matters: A shared spec gives different specialists a way to shape the same implementation. - Specialist contributions without generalism: Distinguish why solo SDD can work for someone with cross-disciplinary skills from why a team should let specialists contribute without learning unrelated skills or answering outside their expertise.
Why it matters: Collaboration should use people’s expertise without making unrelated skills a prerequisite for participating.
Key terms: specification, common control surface, intent, coding agent, solo SDD, generalist, specializations
4.1.1 Three roles at the specification surface
This section maps three contributing roles to specification phases, distinguishes specification authoring from execution, and shows how engineering feedback refines the spec.
- Roles and specification phases: Describe how product specialists, architects, and engineers contribute to the Discover, Design, and Tasks phases, respectively.
Why it matters: The role-to-phase mapping makes each contributor’s responsibility in authoring a specification clear. - Authoring and execution harnesses: Distinguish the Intent Harness, where the roles author specifications, from the Execution Harness, which consumes those specifications and returns implementations.
Why it matters: This distinction separates the team’s specification decisions from the implementation produced from them. - Engineering feedback into specifications: Explain why Engineering includes more than developers and how its specialists can feed problems found during task authoring back into the specification.
Why it matters: Specialists who must execute and verify the work can catch specification gaps before those gaps become unclear completion claims.
Key terms: product specialist, architect, Engineering, Discover, Design, Tasks, Intent Harness, Execution Harness, specifications, implementations
4.1.2 Engineer as scribe
This section explains why having an engineer write everyone else’s specification input is a common but unsustainable collaboration pattern.
- Engineer scribe pattern: Describe why engineers often become specification scribes and how contributions from product specialists, architects, and other roles reach the spec through them.
Why it matters: Recognizing how the scribe pattern arises helps a team see why indirect contribution can become its default. - Costs of indirect authoring: Explain how routing expertise through an engineer can compromise captured intent and delay specification authoring, and why the section calls for first-hand contributions.
Why it matters: First-hand contributions reduce the risk that a specification reflects a scribe’s interpretation rather than the expert’s intent.
Key terms: SDD frameworks, source repository, engineer as scribe, specification artifacts, translation burden, captured intent, subject matter expert, first-hand
4.1.3 Passing the baton
This section describes sequential, role-by-role specification authoring and explains why its handoffs become a collaboration bottleneck.
- Role-by-role specification handoff: Describe how product specialists, architects, and engineers contribute directly to a co-located specification, passing it from one role to the next before pull-request review.
Why it matters: It shows how a team can involve each specialist directly in authoring a specification using a workflow familiar from code collaboration. - Sequential handoff bottleneck: Explain why passing a specification sequentially between roles becomes slow as multiple features are in flight, despite coding agents speeding up each person's contribution.
Why it matters: Faster individual authoring does not make the team's workflow fast when work is queued for clarification and review.
Key terms: Engineer as Scribe, feature branch, pull request, coding agent, specification, sequential handoffs, miniature waterfall, review overhead, shared understanding, Execution Harness
4.1.4 Mob authoring
This section explains how a team can author a specification together to eliminate handoffs, and why the approach creates scheduling and throughput constraints.
- Shared specification authoring: Describe how all roles work with an agent in one session to resolve questions and produce a specification, then send it to the Execution Harness and review the implementation together.
Why it matters: Working together lets the team settle questions immediately rather than waiting for successive handoffs. - Specification production pace: Explain why a weekly mob-authoring session may be sufficient for human implementation but may not keep up with coding agents in the Execution Harness.
Why it matters: The pace of agent implementation can make specification authoring the activity the team must schedule around. - Simultaneous availability constraint: Explain why having every role present makes mob authoring difficult to arrange despite removing handoff queues.
Why it matters: Removing handoffs does not remove coordination costs; it concentrates them in scheduling everyone together.
Key terms: mob authoring, mob programming, Execution Harness, mob authoring session, feature specifications, simultaneous availability, co-located team
4.1.5 Asynchronous contribution through encoded expertise
Recurring guidance from different roles can be encoded as standing context so a team can author specifications asynchronously while reserving reviews and conversations for feature-specific questions.
- Asynchronous role contributions: Explain how recurring constraints, principles, and review criteria from different roles become standing context in the Intent Harness, which the coding agent uses to guide specification authoring even when those roles are absent.
Why it matters: A team can keep authoring a specification without repeatedly gathering every specialist to restate familiar guidance. - Review and conversation focus: Explain why incorporating standing context during specification authoring can reduce repetitive specification and implementation review without replacing direct conversation between roles.
Why it matters: Encoding repeatable guidance makes room for human review and discussion where judgment is still needed.
Key terms: standing context, Intent Harness, product specialist, architect, engineer, specification review, implementation review, feature-specific nuances
4.2 Specifying as a team
As a team begins specifying features, it separates application-wide guidance from feature-specific decisions and builds standing context without a fixed order of contributions.
- Standing Context Versus Feature Decisions: Distinguish recurring guidance that belongs in standing context from decisions that belong in a feature specification, using the URL shortener examples.
Why it matters: This distinction helps the team put each decision where it can guide the right work. - Flexible Standing Context Contributions: Explain how team members can add standing context as SDD adoption begins, without waiting for every role or for a feature specification.
Why it matters: The team can capture useful recurring guidance when it becomes clear rather than waiting for a prescribed handoff.
Key terms: standing context, feature specifications, recurring guidance, SDD, stateless architecture
4.2.1 Product specialist defines the what
The product specialist defines feature intent in Discover conversations while building reusable standing context from product-wide rules, shared language, and recurring questions.
- Product Wide Business Rules: Explain how the product specialist moves rules that apply across features into standing context, using the URL shortener examples.
Why it matters: Shared rules give future features the same product constraints without relying on someone to restate them. - Shared Business Vocabulary: Explain how a shared vocabulary carries business meaning consistently from the product specialist through specifications, agents, and code.
Why it matters: Consistent terms make it easier for the product specialist to check whether the agent captured the intended business meaning. - Recurring Specification Questions: Describe how the product specialist puts mandatory authoring questions into standing context when their answers cannot all be defined upfront.
Why it matters: Reusable questions keep important product decisions from being forgotten when a new feature is drafted. - Discover Conversation Feedback: Describe the product specialist's feature-specific role in Discover and how discoveries there can improve standing context for later features.
Why it matters: Improving standing context during feature work makes future drafts and questions more useful to the product specialist.
Key terms: business rules, standing context, destination, business vocabulary, ubiquitous language, bounded context, mandatory questions, feature specification, Discover conversation, first draft
4.2.2 Architect shapes the how
The architect establishes technical constraints and boundaries as standing context, scopes that context to avoid unnecessary agent overhead, and resolves feature-specific design questions.
- Architectural constraints and boundaries: Explain how the architect shapes standing context through technical constraints, bounded contexts, and interfaces between them, using the URL shortener examples.
Why it matters: These decisions give the agent architectural direction without requiring each feature to redefine the application’s structure. - Relevant standing context delivery: Distinguish how the architect makes boundary-specific and cross-cutting guidance available to an agent without loading irrelevant context for every feature.
Why it matters: Loading guidance only when relevant avoids wasting the agent’s context window on unrelated constraints. - Feature-specific design conversation: Describe how the architect’s role changes after establishing standing context, and identify the kinds of feature-specific questions left for the Design conversation.
Why it matters: Standing context can guide the agent’s design while leaving concrete, unresolved feature decisions for discussion.
Key terms: standing context, constraints, ubiquitous language, bounded contexts, interfaces, folder-level file, AGENTS.md, CLAUDE.md, cross-cutting concerns, skill
4.2.3 Engineer authors the tasks
Engineers turn product intent and architectural design into agent-executable tasks, define how those tasks will be verified, and review the plan before implementation.
- Engineering task list practices: Explain how engineers translate the product specialist’s requirements and the architect’s design into an executable task list, and how standing context shapes the agent’s draft for each feature.
Why it matters: The task list is where the team’s intent becomes a path the agent can execute. - Test driven verification sequence: Describe how acceptance tests and Test-Driven Development can guide implementation of the URL shortener while respecting the architect’s boundaries.
Why it matters: The two kinds of tests connect observable product behavior to implementation within the agreed architecture. - Evidence based task completion: Explain how task checks and optional commit checkpoints provide evidence of completion, including why branch coverage is preferred to line coverage here.
Why it matters: Explicit checks make completion a verifiable claim rather than an agent assertion. - Feature task list review: Describe what engineers review in a generated task list before the agent begins coding and when they refine it.
Why it matters: Reviewing the plan before coding catches missing work and missing proof of completion while they can still be addressed in the tasks. - Evolving verification and human review: Explain how engineers use recurring quality gaps to improve standing context, and why manual code review remains necessary.
Why it matters: Recurring problems become prompts for earlier prevention while people continue to inspect the resulting code.
Key terms: standing context, task list, original intent, acceptance tests, acceptance criteria, Test-Driven Development, unit tests, outside-in verification, checks, quality gates
4.2.4 Beyond the three roles
This section shows how specialists contribute reusable standing context and review new features to keep that context current.
- Specialist security standing context: Explain how a specialist can contribute standing context alongside feature-specific details, using the URL shortener’s redirect safeguards as an example.
Why it matters: Reusable safeguards need not be rediscovered for every feature. - Review and promotion of guidance: Describe how a security specialist checks whether standing context covers a new redirect-rules feature and handles any newly identified recurring rules.
Why it matters: Reviewing new features can reveal safeguards that should carry forward rather than remain one-off advice.
Key terms: standing context, feature-specific details, security specialist, open redirect, security guidance, specification, architecture, task list, implementation
4.2.5 Standing context is grown, not installed
This section explains why teams should grow standing context from repeated experience rather than install extensive guidance upfront.
- Evidence earned standing context: Explain why a team should begin with standing context it already knows and add new guidance only after repeated experience shows that it helps.
Why it matters: This helps the team preserve useful guidance without treating guesses as established practice.
Key terms: standing context, repetition
4.3 Hands-on: building the URL shortener as a team
This section introduces a team URL-shortener exercise and describes two ways to participate.
- Team exercise collaboration formats: Distinguish the two ways to run the group exercise: together on a shared machine or asynchronously through a Git server.
Why it matters: Either format lets the group practice contributing from distinct roles.
Key terms: mob style, asynchronously, feature branch
4.3.1 Exercise Setup
This section sets up a team URL-shortener exercise in SpecKit, maps its commands to the SDD workflow, and explains choices that keep the specification authoritative and team contributions reviewable.
- SpecKit workflow mapping: Trace how SpecKit's commands map to standing context, Discover, Design, tasks, implementation, and verification in the SDD workflow.
Why it matters: The same SDD mental model applies even when the team changes frameworks and coding agents. - Specification quality gates: Distinguish what clarify, checklist, and analyze check, and when each is used.
Why it matters: These checks catch different specification problems before implementation. - Specification-first model effort: Justify why the exercise favors strong specification context over relying on a more capable implementation model, and where greater reasoning effort is better spent.
Why it matters: An apparently correct result is not enough if the decisions behind it were never recorded for future work. - Feature branch collaboration trail: Explain how the SpecKit Git extension supports team collaboration and why commit permission is initially left manual.
Why it matters: The branch makes the evolving specification and each contributor's changes visible to the team.
Key terms: SpecKit, constitution.md, Discover, Design, Execution Harness, /speckit.converge, /speckit.clarify, /speckit.checklist, /speckit.analyze, authoritative source of intent
4.3.2 First slice: each role contributes its part
The section walks through a team’s first URL-shortener feature, showing how each role adds standing context just before its artifact is drafted, then checks alignment, implements, and corrects deviations through the specification.
- Just-in-time role contributions: Trace how the product specialist, architect, and engineer add standing context immediately before specification, design, and task-list authoring respectively.
Why it matters: Staging contributions lets the team see which standing guidance influenced each artifact. - Business rules and feature scope: Distinguish product-wide business rules in the constitution from decisions that belong in this feature’s spec, using link expiration as the example.
Why it matters: Putting a temporary scope choice in standing context makes later changes look like contradictions. - Business-language feature discovery: Describe how the product specialist uses the standing business context during the specify conversation and records further clarifications.
Why it matters: The discovery conversation can settle user-facing behavior before technical design enters it. - Architecture constraints and review: Explain how the architect’s standing constraints guide the plan and how the team checks the resulting design artifacts.
Why it matters: A plan needs to reflect agreed architecture, not merely look complete when generated. - Engineering tasks and alignment: Describe how engineering standing context shapes the task list and how analyze catches disagreements among the spec, plan, and tasks before implementation.
Why it matters: The team can catch a mismatch between its intended quality rules and its implementation tasks before work begins. - Convergence and specification-first repair: Trace the implement–converge loop and explain how the team handles deviations without bypassing the specification.
Why it matters: Keeping corrections in the artifacts preserves the specification as the authoritative account of intent.
Key terms: standing context, constitution, specification artifact, invariants, out of scope, spec.md, /speckit.specify, /speckit.clarify, failure path, clarifications
4.3.3 Second feature: link expiration
The link-expiration example shows how established standing context reduces specification work and directs the agent’s questions toward a consequential product decision.
- Reuse of standing context: Explain why specifying link expiration requires less setup than the first feature: the existing vocabulary, design boundaries, layering, and completion goals already give the agent enough context to help draft the specification.
Why it matters: The example shows how earlier team decisions can reduce the work needed to specify the next feature. - Expired link visitor experience: Explain how standing context sharpened the agent’s scope questions about link expiration, especially the question of what a visitor should see after following an expired link.
Why it matters: It illustrates how shared product context helps surface a decision the product specialist needs to make.
Key terms: standing context, constitution, module boundaries, layering, completion goals, link expiration, visitor experience, generic failure
4.3.4 Reviewing the constitution
The section distinguishes reusable architectural guidance from project-specific constitution content and shows how standing context reduced repeated human input across two features.
- Reusable architectural standing context: Explain why architectural patterns shared across projects should move from each project's constitution into a reusable skill, while project-specific decisions stay in the constitution.
Why it matters: Sharing common guidance in one place avoids duplicating it across repositories without losing each project's distinct decisions. - Standing context and human involvement: Describe how human involvement differed between the first slice and the second feature, and explain what that difference shows about standing context.
Why it matters: Standing context helps agents and new team members follow how the team works without repeatedly asking people for the same decisions.
Key terms: constitution, reusable skill, architect’s standing context, Design conversation, standing context, first slice, second feature
4.4 Making the framework work for us
This section argues that SDD frameworks should fit a team’s existing backlog and delivery workflows so stakeholders can contribute to the Intent Harness.
- Visibility Across Concurrent Features: Explain why teams need to track work across specification, implementation, review, and completion when several features are in flight. Describe why converting generated tasks to issues is only a starting point.
Why it matters: Shared visibility helps a team coordinate work that is happening in parallel. - Framework Fit With Existing Workflows: Justify adapting SDD frameworks to established delivery workflows rather than replacing those workflows with framework defaults. Explain how that integration helps stakeholders contribute to the Intent Harness.
Why it matters: A framework is more useful when it accommodates how the team already delivers software and makes participation practical for every stakeholder.
Key terms: backlog tools, epics, user stories, GitHub Issues, SDD frameworks, existing workflows, Intent Harness
4.5 Summary
The chapter concludes that team-wide SDD depends on organizing contributions to specifications, growing useful standing context, and adapting the framework to existing workflows.
Concepts explained in this chapter
- contextInformation supplied to an AI coding agent to guide its understanding and work.
- product specialistA product-side participant who clarifies feature intent and defines what a feature should accomplish.
- specification authoringSpecification authoring is the structured process of eliciting intent and expressing it as a detailed feature specification.
- specificationA structured description of software intent, requirements, implementation constraints, and expected outcomes.
- Intent-Driven DevelopmentAn AI-native software engineering approach that translates implicit human intent into consistent language and systems that agents can use to guide software development.
- specification-driven developmentA software development approach in which specifications produced through human–AI dialogue guide implementation.
- task phaseThe specification phase in which engineering decomposes design work into executable tasks and defines completion evidence.
- test-driven developmentTest-driven development is a software development practice in which an automated test is written before the implementation that makes it pass.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
