Stack Workflow Grill Log

Initial Situation

Harness currently works epic by epic, often with one PR per epic. Some PRs are dependent, but the default operating model is to merge one PR and then start the next task from the updated trunk. kitlangton/stack introduces a stack-aware PR workflow where dependent PRs can be opened before their parents merge, with GitHub PR bases encoding branch dependencies and stack sync repairing descendants after squash merges.

Issue

The team needs to decide where stack usage becomes mandatory, where it remains advisory, and which Harness phase entrypoints should enforce stack-aware behavior. The main candidate is implement-spec, because it creates implementation work from a dependency graph and can choose whether dependent tasks become a stacked PR chain instead of serial merge waits.

Solution Direction Under Grill

Use stack as a mandatory tool in the Harness capability pack, then define stack-aware gates across planning, implementation, review, delivery, and docs/runbook surfaces. Treat stack sync --dry-run as the default inspection entrypoint and stack sync as the mutation entrypoint once the preview is correct.

Branch: Tool Availability

Q1

Question: Should stack be treated as a mandatory pack tool for Harness PR workflows?

Accepted answer:

• Yes. stack is a mandatory default workflow tool for Harness planning and delivery workspaces. stack sync --dry-run is the required inspection gate, and stack sync is the approved mutation gate when the preview is correct.

Branch: Enforcement Entrypoints

Q2

Question: Which Harness flow entrypoints must become stack-aware?

Accepted answer:

• Primary enforcement belongs in create-spec, not implement-spec. When a new spec begins from backlog context, create-spec must detect whether the target epic/story depends on open PR work and decide whether the new branch/spec should be based on that still-open PR branch.

Q3

Question: Should create-plan turn task-level depends_on relationships into stacked PRs?

Accepted answer:

• No. Dependent tasks inside one epic/plan are part of the same epic delivery and therefore the same PR. Task-level depends_on only controls implementation ordering inside that PR.

Branch: Implementation Branching Policy

Q4

Question: When implement-spec executes dependent tasks, should it create branches from still-open parent branches instead of waiting for merge?

Accepted answer:

• No, not because of task-level dependencies. implement-spec should honor branch/base intent already decided by create-spec and create-plan; it should not reinterpret intra-epic task dependencies as separate stacked PRs.

Branch: Backlog Dependency Policy

Q5

Question: When a new epic/spec depends on backlog work currently represented by an open PR, should Harness create the new PR from the still-open branch and use stack sync?

Accepted answer:

• Yes. create-spec must detect stack intent from backlog dependency metadata plus live open PRs. If the target epic/story depends on another story/epic with an open PR, create-spec records a required Branch/Base Intent section in SPEC.md: parent PR, parent branch, intended child branch, and required stack sync --dry-run gate.

Q6

Question: Should create-spec create or switch git branches immediately when it finds an open parent PR?

Accepted answer:

• No. create-spec stays in requirements/spec space. It records branch/base intent, but actual branch creation or switching belongs to delivery/implementation execution unless the user explicitly asks for branch setup during the spec turn.

Q7

Question: When backlog says the new spec depends on another epic/story, but no open parent PR is found, should missing PR evidence block spec creation?

Accepted answer:

• Yes. Missing parent PR evidence blocks spec creation when the dependency is not already proven implemented. If the dependency is already merged, create-spec records No Stack Required, then verifies dependency readiness by checking that the depending code actually exists and that related spec/plan artifacts exist. If the dependency is not implemented or cannot be proven, execution must block immediately.

Q8

Question: Is the dependency-readiness gate part of stack implementation?

Accepted answer:

• No. Dependency-readiness validation is a create-spec capability. stack only handles open-PR branch/base relationships after create-spec has determined that the dependency is represented by an open parent PR.

Q9

Question: What evidence is required for create-spec to treat a backlog dependency as proven implemented?

Accepted answer:

• create-spec trusts existing IMPLEMENTATION-NOTES.md or an equivalent implemented-status artifact as sufficient proof of implemented dependency readiness. If implemented-status artifact evidence is absent, it falls back to checking local code paths/behavior or merged PR evidence. SPEC.md and PLAN.md alone prove intent, not implementation.

Q10

Question: Should create-plan decide stack topology, or only preserve and validate the stack/dependency decisions from create-spec?

Accepted answer:

• create-plan is a preservation and validation gate only. It must read the SPEC.md Dependency Readiness / Branch/Base Intent section and preserve it into PLAN.md, but it must not decide stack topology itself.

Q11

Question: Should implement-spec create or switch branches automatically from recorded Branch/Base Intent?

Accepted answer:

• Yes. implement-spec must enforce branch/base intent before coding. If PLAN.md contains Branch/Base Intent, implement-spec verifies the current branch is based on the intended parent branch or automatically creates/switches to the intended child branch before implementation begins. It runs stack sync --dry-run after PR creation/update, not necessarily before coding.

Q12

Question: Should implement-spec require a PR before coding, or create/update the PR after implementation?

Accepted answer:

• Harness defaults to PR-after-implementation. implement-spec creates/switches the intended branch, implements, commits, pushes, creates or updates the PR with the recorded base, then runs stack sync --dry-run and stack sync when the preview is correct. Early draft PRs are optional only when explicitly requested.

Q13

Question: How should delivery and review split stack closeout responsibility?

Accepted answer:

• delivery-phase owns stack cleanliness and mutation before closeout. Whenever a PR exists, delivery must run stack status and stack sync --dry-run. If the PR is stack-dependent and dry-run shows pending changes, delivery must run stack sync before closeout. review-phase stays readonly: it uses the actual PR base and includes stack status as review evidence, but does not mutate stack state.

Q14

Question: Where should stack live as a mandatory Harness tool, and what happens when it is unavailable?

Accepted answer:

• Add stack as a required external tool for the planning/delivery/default workflow surface, not as a framework-specific pack. Add a local stack skill copied from or adapted from kitlangton/stack so agents know exact commands. Missing stack blocks stacked-PR workflows, but does not block independent trunk-based work.

Q15

Question: What section shape should create-spec write and create-plan preserve for dependency readiness and stack intent?

Accepted answer:

• Use Dependency Readiness whenever backlog dependencies exist. Its fields are Status, Dependency, Evidence, and Reason. Status is one of No Stack Required, Branch/Base Intent, or Blocked.
• Include Branch/Base Intent only for stack-dependent work. Its fields are Parent PR, Parent branch, Child branch, PR base, and Required gate.

Example:

## Dependency Readiness

- Status: No Stack Required | Branch/Base Intent | Blocked
- Dependency: <epic/story/pr/link>
- Evidence: <implementation notes path | merged PR | parent PR>
- Reason: <why this status was chosen>

## Branch/Base Intent

- Parent PR: #123
- Parent branch: team/stefan/parent
- Child branch: team/stefan/child
- PR base: team/stefan/parent
- Required gate: stack sync --dry-run after PR creation/update

Glossary Decisions

Glossary Q1

Question: What is the canonical distinction between task dependencies and PR stack dependencies?

Accepted answer:

• Canonical term: Task Dependency — an implementation ordering relationship inside one epic/plan and normally inside one PR.
• Canonical term: Backlog Dependency — an epic/story dependency that may require a new spec or PR to build on work from another open PR.
• Avoid: using depends_on alone to mean stacked PR dependency.
• Axiom: Intra-epic task dependencies do not create separate PRs by default.
• Axiom: create-spec records stack intent; it does not mutate git state by default.
• Axiom: Dependency readiness is a create-spec gate, not a stack feature.
• Axiom: If a backlog dependency is neither proven implemented nor represented by an open parent PR, spec creation blocks.
• Axiom: IMPLEMENTATION-NOTES.md or an equivalent implemented-status artifact is trusted as sufficient readiness proof.
• Axiom: SPEC.md and PLAN.md prove intent, not implementation.
• Axiom: create-plan preserves and validates stack/dependency decisions; it does not decide stack topology.
• Axiom: implement-spec may create or switch branches automatically when Branch/Base Intent is recorded.
• Axiom: PR creation defaults to after implementation; early draft PRs are opt-in.
• Axiom: stack sync runs after PR base metadata exists.
• Axiom: Delivery owns stack mutation and cleanliness; review reports stack evidence only.
• Axiom: Missing stack blocks stack-dependent workflows, not independent trunk-based work.
• Axiom: Dependency Readiness is present whenever backlog dependencies exist; Branch/Base Intent appears only for stack-dependent work.

Branch: Documentation And Runbooks

Q16

Question: Should stack workflow behavior be repeated in root AGENTS.md or scaffolded prompt guidance?

Accepted answer:

• No. Root AGENTS.md / scaffolded prompt repetition is not useful when the behavior is already pinned in the relevant phase skills. The phase skills are the enforcement source of truth; duplicated standing-rule prose risks drift.

Q17

Question: Should Harness add a standalone human-facing stack workflow runbook now?

Accepted answer:

• No. Do not add a standalone human runbook for now. The local stack skill plus phase skill instructions are canonical. Add human docs only later if implementation changes visible operator workflow or users are expected to run stack manually outside the phase skills.

Final Axioms

• Stack workflow docs are skills-first; no standalone human runbook is needed initially.