Product Manager
The developer environment isn't where engineers work. It's where product decisions get made — with an AI coding agent that can build, iterate, and validate in the same session you're thinking. PMs working in the harness don't just write better requirements. They generate working prototypes, gather real feedback, and produce downstream artifacts from what was actually validated. The ProductHarness context keeps every output production-aligned. Distribution is what happens after all of that.
This is the complete workflow reference — used during and after training, built to be navigated, not read end-to-end. New to the framework? Start with the shorter case for what changes: For Product Managers.
What Has Changed
The job has changed. Not just the overhead — what the role is capable of has expanded in ways that matter.
The prior model: the PM specifies what to build, produces a document, hands it to design and engineering, and waits for something to react to. The Translation Tax — converting intent into the right format for each downstream system — is real and worth removing. But removing that overhead doesn't change what the PM can produce. It just makes the existing work slightly less painful.
What's different in the developer environment with an AI coding agent and ProductHarness context active is what's now possible at all. The PM can now iterate on ideas and generate working prototypes — not mockups, not wireframes — working code that runs and behaves — in the same session they're thinking through the product problem. They can share those prototypes with stakeholders and get genuine feedback on how something works, not on whether a description sounds right. They can refine, rebuild, and revalidate before engineering has been asked to write a line of code. And the requirements, acceptance criteria, and metadata that emerge from that process come from something that was built and tested — not from speculation about what should be built.
The ProductHarness context is what makes this different from a throwaway spike. The steering documents encode the org's decisions: component library, API patterns, authentication approach, data handling, CI/CD requirements. When the agent generates code, it reads those documents. Every prototype follows those conventions. A PM iterating on a new feature with the agent gets working code that uses the org's actual patterns — code that engineering can inherit and extend rather than rebuild to production standards from scratch.
Distribution — publishing to the backlog, generating test cases, syncing artifacts — still happens, and the Translation Tax is still worth removing. But it's now the final step in a process that starts with building and validating, not the primary value the model delivers.
Where You Do This Work
PMs working in ProductHarness don't write requirements in a document editor or paste them into a ticket. They work in an IDE or CLI — the same kind of environment where engineers write code — with an AI coding agent that has the entire repository as context. This isn't a stylistic preference. The environment is what makes the model work, and it's what makes it possible for a PM to build, not just specify.
The AI coding agent lives in the developer environment. Work that lives inside that environment — requirements, prototypes, decisions, standards — is always in context. The agent can act on any of it, at any time, without being handed a copy.
When you write requirements in the repo and open it in an AI-enabled IDE or CLI tool, the agent can see your requirements files alongside existing code, steering documents, architecture decisions, and previous work. It isn't reasoning from a summary you paste into a chat window. It has everything — and that's what makes its output trustworthy enough to act on.
When requirements live in markdown files in a Git repository, they inherit every property of code: version control, branching, diffs, merge requests, blame, history. A requirement that changed can be traced. A revision that introduced an ambiguity can be identified. The full intent and reasoning behind a product decision is available — not locked in someone's head or buried in a long Slack thread. This is what "requirements as code" means: not that requirements look like code, but that they behave like it.
The mechanism for coordinating product work becomes the same mechanism for coordinating engineering work: branches, pull requests, reviews. A PM can propose requirement changes in a branch. Engineers can review and comment before the requirements are merged. The history of those decisions lives alongside the requirements themselves — not scattered across email threads and meeting notes.
Any AI coding agent that operates on a local repository works: Cursor, VS Code with a Claude or Copilot extension, Claude Code (CLI), or similar. The agent needs to read files in the repo and take actions from prompts. Any tool that meets those criteria activates the full ProductHarness workflow — including prototype generation. PMs don't need to know how to code. They need to know how to describe what they want and judge what comes back.
Building and Validating in the Harness
The most significant change in the PM role is compression: the time between "I have an idea" and "I have something real to react to" has collapsed. In the developer environment with an AI coding agent and ProductHarness context active, a PM can generate a working prototype of a feature in the same session they're thinking through the product problem — then iterate on it, share it, gather feedback, and refine until the solution is actually right. Before engineering has been asked to write a line of code.
A working prototype generates better feedback than a requirements document. "Does this solve your problem?" gets a different answer when the person can use the thing — not read about it.
The steering documents in the harness encode the org's decisions — component library, API patterns, authentication approach, data conventions, CI/CD requirements. When the agent generates a prototype, those documents are in context. The result isn't demo-ware built to be thrown away. It's code that follows the org's actual conventions, uses the org's actual components, and handles auth and data the way production handles them. Engineering inherits something they can extend, not rebuild.
Traditional product development: PM writes requirements → design creates mockups → engineering builds → PM reacts to what was built → revision cycle. That loop takes weeks. In the developer environment: PM describes concept → agent generates prototype → PM iterates ("show the empty state," "what does the error condition look like," "add the loading state") → PM and agent refine until it's right → stakeholders react to something working. That loop takes hours. The decisions that used to happen after engineering built the wrong thing now happen before engineering starts.
Stakeholder feedback on a static mockup or a requirements document is feedback on a representation of the thing. Stakeholder feedback on a working prototype is feedback on the thing. "I think I'd want to see the full list before filtering" is a comment on a Figma frame. "I keep clicking this to go back and there's nothing there" is feedback from using a working implementation. The second kind surfaces real problems. The first kind surfaces imagined ones — and misses the real ones.
When the solution is developed iteratively and validated before engineering starts, the requirements and acceptance criteria that emerge from that process describe what was built and tested — not what the PM hoped would be built. Edge cases appear when something is built and the edge is encountered. Data requirements become clear when the prototype needs to read or write data. Non-functional requirements surface when the prototype is shown to users who try things the PM didn't anticipate. This is not a better way to write requirements. It's a different origin for them — and the difference is the accuracy of what's captured.
As the solution is developed and validated in the harness, the metadata that downstream steps depend on becomes available without a separate documentation exercise. The acceptance criteria describe validated behavior. The data model reflects what the working prototype actually needed. The edge cases are the ones that were discovered in iteration, not the ones someone tried to imagine. The test cases map to behavior that exists and was tested. This is what makes the downstream lifecycle steps — backlog, QA, engineering handoff — more reliable: they're working from artifacts grounded in something real.
"Build a working prototype of [feature] using our component library and API patterns."
"Show me what the empty state looks like for this feature."
"Add the error state for when [condition] occurs."
"What does this look like on mobile?"
"The user has partial data — only [fields] are populated. Show me that state."
"Iterate: the stakeholder feedback was [X]. Make that change and show me the result."
"Based on what we built, draft the acceptance criteria that describe this behavior."
"What data does this prototype read and write? Draft the data requirements from that."
"What edge cases did we encounter in building this that should be in the requirements?"Enriching Requirements Before They Reach Anyone Else
Whether requirements emerged from an iterative prototype session or were written more directly, the agent can systematically improve them before they leave the repo. This isn't a substitute for building and validating — it's a final quality pass that closes gaps the iteration process may have left open.
A PM working with an AI coding agent doesn't just write requirements faster. The agent provides a systematic pressure-test across dimensions no single reviewer consistently holds simultaneously.
What that looks like across the dimensions of requirements quality:
The agent reads your acceptance criteria with fresh eyes and full repo context — it isn't anchored to your intent the way you are. It can identify what the criteria imply but don't state, what conditions aren't covered, and what assumptions are embedded in the language you chose. A gap caught here costs a conversation. A gap caught in testing costs a sprint.
PMs write requirements from the happy path. The agent has no happy path bias. It will systematically surface: what happens with empty state, partial data, network failure, concurrent users, invalid inputs, permission boundaries, and unusual but valid sequences. These are the scenarios that become bugs when they're discovered by QA — or, worse, in production. Getting them into requirements means engineering designs for them from the start.
Many acceptance criteria that feel complete aren't testable. "The page should load quickly" is not testable. "The page should load in under 2 seconds on a 4G connection" is. "The UI should be accessible" is not testable. "The component meets WCAG 2.1 AA standards" is. The agent can identify criteria that rely on subjective judgment and help rewrite them as observable, measurable conditions — which makes QA's job possible and removes interpretation ambiguity from engineering.
Features that touch data — which is most features — have data requirements that PMs often leave implicit. What states does this data exist in? What validation rules apply? What happens when the data is missing, partial, or malformed? What existing data structures does this feature read from or write to? The agent can surface these questions from the requirements before engineering has to ask them in refinement — or worse, make assumptions that produce the wrong behavior.
Requirements are written in isolation; systems aren't. The agent can identify: other features in the repo that this change interacts with, API contracts that need to be defined before engineering starts, teams or systems outside this repo that need to know about this feature, and dependencies on work that isn't yet complete. These are the conversations that typically happen at the start of a sprint. Having them at the end of requirements writing compresses the loop significantly.
Performance, accessibility, security, privacy, rollback behavior, degradation modes — these are the requirements that live outside the happy path and outside the visible UI. They're also the ones most frequently omitted from requirements and most painful to retrofit. The agent can systematically check for each category and surface what's missing for the specific type of feature being specified.
Requirements that seem complete from a PM's perspective often have gaps that are only visible from engineering's perspective or QA's. The agent can simulate those perspectives: "What questions will engineering ask when they pick this up?" and "What will QA need to write test cases that these requirements don't provide?" surface the exact information that causes refinement meetings to run long or tickets to be bounced back. Getting those answers into the requirements file closes the loop before it opens.
The PM Workflow
After building and validating (see Building in the Harness above), open the requirements file for your feature area and formalize what was built and tested into structured acceptance criteria. This is the source of truth — everything downstream derives from it. Requirements at this stage describe working behavior, not intended behavior.
The agent handles: Drafting requirements from the prototype session. Give the agent a summary of what was built, what stakeholders reacted to, and what decisions were made. It drafts the requirements; you refine and own the result.
PM decides: What did validation confirm? What changed from the original idea? What's definitively out of scope? These are judgment calls grounded in what was actually tested — not abstract intent.
This is not a one-pass review before publishing. This is the core loop — and it's where the most PM value comes from. The agent has full context of the repo: your requirements, existing features, technical standards, prior decisions. Use it to systematically stress-test and enrich your work product across every dimension a downstream team will depend on.
Work through these categories iteratively. Not all apply to every feature, but run through them before you consider requirements ready for anyone else:
"Review the acceptance criteria for [Feature]. What's missing?"
"What scenarios aren't covered by these criteria?"
"What questions will engineering have when they pick this up that aren't answered here?"
"What will QA need to write test cases that these requirements don't provide?""What are the edge cases for [Feature] that these criteria don't address?"
"What happens if [condition]? Is that covered?"
"What failure states does this feature need to handle?"
"What's the behavior when the user has no data, partial data, or corrupted data?""Which of these acceptance criteria are not testable as written?"
"Rewrite [criterion] so it's specific enough to generate a pass/fail test."
"Rewrite the acceptance criteria in Given/When/Then format."
"Flag any criteria that rely on subjective judgment rather than observable behavior.""What data does this feature need to store, read, or transform?"
"What are the data states this feature needs to handle? Empty, partial, error, loading?"
"Are there data validation rules implied by these requirements that aren't stated explicitly?"
"What existing data structures in the codebase does this feature interact with?""What other features or systems might be affected by this change?"
"Does this feature have dependencies on anything not yet built or in progress?"
"Are there API contracts implied by this feature that need to be defined before engineering starts?"
"What teams outside this one need to know about this feature before it ships?""What performance requirements apply to this feature that aren't stated?"
"What accessibility requirements apply here?"
"Are there security or data privacy considerations not addressed in these criteria?"
"What are the rollback or degradation requirements if this feature fails in production?""What open questions need answers before this feature is ready for design?"
"What would block engineering from starting on this today?"
"Score these requirements on completeness, testability, and ambiguity. What needs work?"The agent handles: Systematic review across dimensions a single reviewer doesn't hold simultaneously — gaps, edge cases, testability, data needs, dependencies, non-functionals. It has full repo context and no cognitive blind spots about what you intended to write.
PM decides: Which findings to incorporate. What the acceptance criteria should actually say. When the requirements are ready. The agent surfaces the issues; the PM makes every call.
Once satisfied with the requirements, ask the agent to create backlog artifacts. The PM never opens the backlog to type anything — the repo is the source, the backlog is the tracking mirror.
"Create a story in [PROJECT] from the [Feature] requirements. Include the acceptance criteria as the description."
"Create an epic for [area], then create stories for each feature. Link the stories to the epic."
"Update [TICKET-ID] with the revised acceptance criteria."The agent handles: Story creation, epic creation, ticket updates, field assignment.
PM decides: When requirements are ready to publish. Which project and epic to link to.
Once requirements are in the repo and backlog tickets exist, test cases can be created from the same source. The acceptance criteria become the test plan — no manual translation needed.
"Create test cases in [PROJECT] from the [Feature] acceptance criteria. Link them to [TICKET-ID]."The agent handles: Test case creation with steps derived directly from acceptance criteria, linked to the backlog story.
PM decides: When to kick this off — or whether to hand it to QA to coordinate.
As designers generate components and QA validates them, you can see results in Storybook: every component that's been generated, different states (default, error, loading, disabled), and whether what was built matches what was specified.
The agent handles: The technical work of component generation and state management.
PM decides: Whether the implementation matches the intent. What to flag for revision.
When a component passes visual review and QA tests are passing: check the engineering handoff checklist, confirm all acceptance criteria are covered, and mark the component ready. For backend features, handoff criteria include API contract tests green, relevant tests passing, and rollback procedures documented.
The agent handles: Tracking status in the manifest, surfacing what's ready and what's not.
PM decides: Whether to approve for handoff. This is a judgment call — not a checkbox.
When writing requirements for features that touch existing systems, use the agent to pull in relevant documentation and context without manual searching.
"Search [knowledge base] for existing documentation about [topic or feature area]."
"Find the [process] documentation — I need to understand what's required before we can deploy to production."The agent handles: Searching org documentation, synthesizing relevant context into your requirements session.
PM decides: What context is relevant to incorporate and how.
How to Write Effective Requirements
The ProductHarness requirements template has five sections. Three are standard. Two are required-but-bypassable — fields that every spec must address, but that have an explicit bypass path when they genuinely don't apply. The bypass requires a stated reason. That makes the exception auditable; it prevents silent omissions.
Required-but-bypassable means: you can't skip OKR or Validation Approach — but you can replace them with a sentence explaining why they don't apply to this feature. The reason is the record. "TBD" and blank are not bypasses.
## Feature: [Feature Name]
### Problem Statement
[What problem does this solve? Who experiences it?]
### OKR ← required-but-bypassable
[Who does what by how much? Include baseline and target.]
[To bypass: state in one sentence why an OKR doesn't apply.]
### Instrumentation
[What events or signals confirm this is working post-launch?]
[Flag any new events engineering needs to add alongside the feature.]
### Acceptance Criteria ← Given/When/Then required
- Given [precondition], when [action], then [expected outcome]
- Given [precondition], when [action], then [expected outcome]
- [Non-functional: e.g., meets WCAG AA color contrast 4.5:1 minimum]
### Validation Approach ← required-but-bypassable
[How will this be validated with real users and at what stage?]
[To bypass: state in one sentence why external user validation doesn't apply.]
### Open Questions
- [Unresolved question that needs an answer before design/engineering]The OKR format is "Who does what by how much?" — it must name a metric, a baseline, and a target. "Improve engagement" is not an OKR. "Increase notification open rate for active users from 12% to 20% by Q3" is. The instrumentation section forces the question of how that metric will actually be measured — declared at spec time, not after launch.
Acceptance criteria must be in Given/When/Then format. This isn't a preference — it's what enables direct generation of automated test cases. Given sets the precondition. When names the action. Then states the observable, specific outcome. Criteria that rely on subjective judgment ("should look clean," "should feel fast") are not criteria; they're deferred decisions that will become arguments in QA or production.
Concrete example:
## Feature: Notification Banner
### Problem Statement
Users miss critical system alerts when they appear only as transient toasts.
Persistent banners give users actionable context when they return to the page.
### OKR
Reduce support contacts related to missed system alerts (operations team)
from 18 per week to under 10 per week by end of Q3 2026.
### Instrumentation
- Track: banner_viewed, banner_dismissed (add to analytics — flag for engineering)
- Existing: support_contact_submitted (already tracked via ticket system)
- Baseline: 18 alert-related support contacts/week
### Acceptance Criteria
- Given a banner with a message and severity level, when the page loads, then both are displayed
- Given a dismissable banner, when a user clicks dismiss, then the banner is removed from view
- Given info, warning, or error severity, when the banner renders, then the correct variant styling applies
- The banner meets WCAG AA color contrast (4.5:1 minimum)
### Validation Approach
Usability test with 5 ops users before design review.
Success signal: users notice and correctly interpret the banner without prompting.
### Open Questions
- Should dismissal persist across page refreshes for the session?
- What is the maximum message length before truncation?Commit this to the repo. It's versioned, reviewable, and always available to the agent as local context. Why not write in the backlog directly? The repo is the source of truth. Requirements here are version-controlled, reviewable in merge requests, and readable by the agent without API calls. The backlog gets a copy — the repo has the original.
decisions/ — Durable Product Reasoning
Engineering teams have Architecture Decision Records — ADRs — to capture why the codebase is built the way it is. Product teams rarely have an equivalent. The result: context lives in people's heads, and when someone asks "why do we do it this way?" the answer is lost, inconsistent, or never given.
Decision records are first-class harness content, storing the reasoning behind significant product decisions — visible to new team members, readable by the agent when generating future work, and available in code review when a proposed change touches a previously-decided area. Feature-scoped decisions live with the feature (docs/work/<feature>/decision-*.md); cross-feature architecture decisions live in docs/decisions/.
A decision record is steering, not just documentation. The agent draws on it when helping with related features. If a proposed requirement conflicts with a prior decision, the agent surfaces the conflict — rather than generating something inconsistent with a call the team already made.
A decision is worth recording when it was a real choice between alternatives, had meaningful downstream consequences, and would be confusing or risky to revisit without knowing the original reasoning. Not every call needs a record — reserve them for decisions with weight.
What situation made this decision necessary? What constraints, data points, or stakeholder inputs shaped the options? Write as if explaining to someone who just joined the team with no prior context. The context section is what the agent reads to know when this decision is relevant.
What alternatives were on the table? List them with honest pros and cons. Vague justifications ("this was better") are less useful than the actual trade-offs. A new team member — or a PM doing related work two quarters from now — needs to understand what was actually weighed.
State the decision clearly in one or two sentences. Then explain why this option was chosen — including what the team explicitly chose not to optimize for. Honest rationale is more useful than a justification. The things that were deprioritized are as instructive as the things that were prioritized.
What does this decision unlock, constrain, or foreclose? How should the agent apply this decision to future work in this area? Include what would cause this decision to be revisited: a market shift, new data, a specific threshold crossed. Consequences are instructions to the agent — and to the next PM who works in this area.
# Decision: [Short Title] (filename: YYYY-MM-DD-short-title.md)
## Context
[What made this decision necessary? What pressures, constraints, or data shaped it?]
## Options Considered
### Option A: [Name]
Pros: [List] Cons: [List]
### Option B: [Name]
Pros: [List] Cons: [List]
## Decision
[One or two sentences. Name the option chosen.]
## Rationale
[Why this option? What was deprioritized? What would cause this to be revisited?]
## Consequences
[What this unlocks or forecloses. How the agent should apply it to future work.]"We decided to [decision]. Draft a decision record with the context, options, and rationale I've described."
"Review this decision record — is anything missing that would make it useful steering for the agent?"
"Search decisions/ for any prior decisions that affect [feature area] before I write these requirements."Discovery
For larger, more ambiguous work — start upstream of requirements. When the problem itself isn't clearly defined, or competing definitions exist, use the discovery nodes before writing requirements.
Skip Discovery
Well-understood problem, clear solution. Go straight to requirements.
Bug fixes, UX polish, enhancements to existing patterns.
Problem Framing
New capability with some uncertainty. Run Problem Framing before writing requirements.
Confirms the team agrees on the problem before solution work begins.
Full Discovery
Strategic initiative, significant investment, high uncertainty. Work through relevant discovery nodes first.
Problem Framing → Opportunity Assessment → Solution Discovery → Validation.
Three Publishing Channels
Work tracking for the teams doing the work. Audience: Engineering, QA, PM, Design. When: after requirements are written and agent-reviewed, open questions resolved. The agent creates stories, epics, and test cases linked to acceptance criteria. The PM never opens the backlog to type anything.
"Create a story in [PROJECT] from the [Feature] requirements. Set priority to High."Cross-org discovery. Where the rest of the organization finds out what is being built, why, and what has been decided. Audience: anyone outside the repo — other PMs, sales, customer success, marketing, executives. The PM decides what is ready for broad visibility. The agent publishes from existing repo artifacts — no rewriting required.
"Publish the Problem Framing for [initiative] to [wiki]. Write a brief intro that explains why this matters."
"Create a release notes page for [initiative] summarizing what shipped and what teams should know."Targeted socialization when broad wiki visibility isn't right — content that's sensitive, early-stage, or strategic; a specific audience rather than the general org; or timing-controlled communication that doesn't need a permanent wiki record.
"Write an executive briefing on [initiative] for the VP of Marketing. She needs to understand the problem we're solving, why now, and what to expect at launch. Two pages maximum."Tips for Better Output
Vague criteria produce vague tests. "The card should look good" is not testable. "The card meets 4.5:1 color contrast ratio" is. Specificity at this step pays forward through the entire chain.
It maps cleanly to test cases and is unambiguous for both humans and AI. "Given a dismissable banner, a dismiss button is visible and functional" — three words of structure that eliminate hours of interpretation downstream.
Telling the agent what you're not building is as valuable as what you are. It prevents scope creep in generated artifacts and eliminates the "we assumed this was included" conversation.
If acceptance criteria change after backlog tickets and test cases were created, re-run the publish flow. The agent can update existing tickets from the updated source. The repo is the record — keep it current.
Context about why particular product decisions were made informs future AI assistance and is invaluable for team continuity. The agent draws on docs/decisions/ when generating work in areas those decisions govern — a decision record is steering, not just documentation. See the decisions/ section above →
Your First Week
Day one actions: Confirm you have the prerequisites — Git installed, access to your org's repo instance, and a repo set up by your Director or designated team member. Pick one feature: something real, something in your near-term backlog, small enough to finish in a few hours but representative of your normal work. Write the acceptance criteria in the repo using the requirements file structure above. Ask the agent to review them. Publish to the backlog. See what comes out.
Week one milestone: You have run the full workflow end-to-end for at least one feature — requirements written in the repo, reviewed by the agent, published to the backlog as a story, and test cases created from the same source. You have seen the output and made at least one refinement cycle. You have a working sense of what "good requirements" produces downstream. Everything after that is iteration.