Planning / Development Process

GitHub Issues hold bug reports, feature proposals, evidence, and active discussion. PRDs record agreed product intent and user stories. ADRs record significant technical decisions and their rationale. These documents serve people and agents across the workspace.

Document ownership

Link to the source document instead of copying its content. Issues preserve discussion; PRDs and ADRs summarize the conclusions. Shipped code provides delivery evidence. It does not determine product intent.

Workflow

1. Use a GitHub Issue when a bug or feature needs discussion, evidence, alternatives, or asynchronous coordination.
2. Read the relevant Issues, PRDs, ADRs, architecture references, and domain vocabulary before you propose changes.
3. For a new capability or meaningful behavior change, create or update a PRD with observable acceptance criteria.
4. For an architecturally significant choice, create an ADR and link the requirements that drive it.
5. Link the originating Issues from the records, and link the records from the Issues when authorized.
6. Write documentation and implementation together when useful. Resolve blocking questions before acceptance.
7. Obtain human acceptance of PRDs and ADRs during review, before merge.
8. Link the relevant stories, ADRs, and originating Issues from the implementation PR.
9. Update affected records, PRD Implementation sections, and architecture references in the same change as the implementation.
10. Verify the acceptance criteria and record the evidence in the pull request before describing behavior as delivered.

An Issue can exist without a PRD or ADR. A defined task can proceed without an Issue. One Issue can cover several stories. A Proposed PRD or ADR can support discussion before the team settles a question. An Issue comment does not override an accepted PRD or ADR. Incorporate agreed changes through the revision rules below.

A discussion-only Issue is complete when its question is resolved. An implementation Issue is complete when its stated completion criteria are met. Writing a PRD or ADR does not complete implementation work. Keep Issues open for remaining work, or link separate delivery Issues. Use the repository's Issue conventions and triage labels.

Examples

PRD lifecycle

Copy the PRD template into docs/concourse/product/prds/. Use the next four-digit number and a short title, such as 0001-organization-access.mdx. The PRD sequence is separate from the ADR sequence. State the affected apps, packages, or shared capability in Scope. Add the record to the PRD index and sidebar metadata.

• Proposed: Requirements are under definition or review.
• Accepted: The decision maker accepts the requirements for the current capability.
• Retired: The capability is no longer offered. Keep a short history only when it explains the current capability.

An accepted PRD describes behavior that exists in the current checkout. Record delivery evidence in the implementation pull request. Keep active task tracking in Issues. For a material change, draft a revision and return its status to Proposed. Human review restores Accepted after the questions are resolved and the behavior is implemented.

Each story has a stable ID, such as PRD-0001-US-01, and observable acceptance criteria under Done when. Each story has a Story status of Current or Retired. Current means the requirement describes behavior in the checkout. A Retired story is a short historical note and no longer defines required behavior. Replaces links to the previous story; Replaced by links to its replacement. Use N/A when no related story exists. Write User need as “As a …, I want …, so that …”. Describe product outcomes in Requirement. Keep technical rationale and consequences in ADRs and detailed designs in linked design artifacts.

For a material revision:

1. Update the affected requirements in place.
2. Preserve IDs when their meaning remains compatible with existing references.
3. For a removed or substantially different outcome, set the old story's Story status to Retired.
4. For a replacement outcome, assign a new story ID.
5. For a replacement, link the old story under the new story's Replaces field.
6. For a replacement, link the new story under the old story's Replaced by field.
7. Keep retired IDs reserved and their headings available for existing links.
8. Add a short revision entry with the date, affected IDs, and reason. Link a related Issue or PR when one exists.
9. Update the last-reviewed date and the Implementation section after review.
10. Update user documentation after you verify the accepted behavior.

Changes to goals, scope, flows, requirements, acceptance criteria, measures, or user-visible terms are material revisions. Spelling, formatting, and link repairs do not need revision entries. For a template section that does not apply, explain why.

Architecture Decision Records

An ADR states one current, lasting technical choice across package or runtime boundaries, its reason, and its consequences. Do not create one for product behavior, a package's local implementation, a working rule, or a temporary optimization. Use the PRD, package guide, standard, or command reference that owns that subject. Copy the ADR template into the decisions directory. Use the next four-digit number and a short title. Name the decision maker.

A new record starts as Proposed. After review and implementation, set it to Accepted. Keep the selected design in the main text. Put an earlier choice in a short history note when it explains the current design. If a later choice replaces an ADR, move useful context into the new record and remove the obsolete file. Renumber surviving records in order, then repair repository links and references in the same change. Git history retains the full discussion and earlier document versions.

Update the decision index, sidebar metadata, architecture overview, and affected PRDs with the implementation.