Proposal: decide where workflow phases (apply/archive/sync) are configured — schema.yaml, config.yaml, or both #1456

Activity

1. clay-good

   added

   enhancementNew feature or requestNew feature or request

   cliCLI commands, output, flagsCLI commands, output, flags

   design-reviewNeeds product/design decisionNeeds product/design decision

   schemaSchema systemSchema system

   backlogReal issue or feature queued for later implementationReal issue or feature queued for later implementation

   on Jul 27, 2026
2. SuhaibAslam commented on Jul 29, 2026

   

   SuhaibAslam

   on Jul 29, 2026

   Contributor

   More actions

   Intent reconciliation as an acceptance case for the operation model

   I have a concrete workflow that may help answer the open questions in this
   issue: reconcile implementation discoveries before archive.

   User flow

   1. A human approves an intent artifact: desired outcome, constraints,
      non-goals, and success evidence.
   2. The agent plans and applies the change.
   3. During implementation, the agent records decisions that were not known when
      the planning artifacts were written.
   4. After implementation, the human accepts, rejects, or supersedes each
      proposed decision.
   5. Archive is unavailable until the reconciliation is complete.

   The important distinction is that this is not more advice for apply or
   archive. It is a post-apply operation with a durable output and a
   deterministic precondition for archive.

   Why the current schema cannot model this faithfully

   The current artifact graph is a planning graph:

   • detectCompleted() in src/core/artifact-graph/state.ts treats an artifact
     as complete when any file matching generates exists.
   • generateApplyInstructions() in
     src/commands/workflow/instructions.ts checks apply.requires only before
     apply, then loads every existing artifact as context.
   • ApplyPhaseSchema in src/core/artifact-graph/types.ts supports one
     pre-apply requirement list and an optional checkbox tracking file. It has no
     post-apply output or operation dependency.
   • The generated archive workflow warns about incomplete artifacts and tasks but
     permits the user to proceed. The direct openspec archive path does not use
     the artifact graph as an archive gate.
   • operations.<phase>.guidance is explicitly advisory, so it cannot honestly
     express "do not archive while decisions are unresolved."

   A custom schema can create intent.md and an initially empty
   decision-log.md, and its apply instruction can ask the agent to update the
   ledger. It cannot make a later reconciliation artifact become ready only after
   implementation or fail closed when archive is invoked directly. Claiming that
   it can would turn a prompt convention into a false safety guarantee.

   Smallest operation model that would cover the case

   One possible shape is:

   operations:
     apply:
       requires:
         artifacts: [tasks]
       tracks: tasks.md
   
     reconcile:
       requires:
         artifacts: [intent, decision-log, tasks]
         tracking_complete: tasks.md
       produces: reconciliation.md
       instruction: |
         Review each implementation decision with the human.
         Record accepted, rejected, and superseded outcomes.
   
     archive:
       requires:
         operations: [reconcile]

   This is illustrative rather than a request to adopt these exact keys. The
   required semantics are:

   • operations have a namespace distinct from artifact IDs;
   • an operation may have durable output;
   • operation readiness may depend on tracked implementation completion, not
     only file existence;
   • archive preconditions are evaluated by the CLI and fail closed in interactive
     and JSON modes;
   • project guidance remains advisory and separate from these checks;
   • the generated skills and direct CLI command observe the same gate.

   The durable reconciliation output could initially use file existence as its
   completion signal, matching current artifact semantics. A later validation
   contract could make content-level states such as pending and approved
   machine-checkable, but that does not need to block agreement on the lifecycle
   shape.

   Relationship to the linked issues

   • Proposal: decide where workflow phases (apply/archive/sync) are configured — schema.yaml, config.yaml, or both #1456: this is evidence for treating apply, reconcile, and archive as
     first-class operations with a namespace separate from artifacts.
   • Support schema extension or partial overrides to avoid full shadowing of built-in schemas #1074: shipping this only as a full schema fork would inherit the maintenance
     problem described there. Composition or explicit extension would let a
     reconciliation layer build on spec-driven.
   • Feat : Add Extensible Hook Capability to OpenSpec Archive Operation #682: prompt hooks can record decisions, but a post-archive hook is too late
     and an advisory pre-archive hook is not a deterministic gate. The use case
     needs an operation precondition rather than arbitrary subprocess execution.

   Suggested next decision

   Before implementation, can maintainers confirm whether operation outputs and
   operation-to-operation requirements belong in the phase model being considered
   here? If yes, I can turn this acceptance case into an OpenSpec change proposal
   and start with the namespace/readiness contracts before adding any
   intent-specific schema.

   ---

   Disclosure: drafted with assistance from Codex (GPT-5).

   ❤️React with ❤️2Reacted by Clay Good and Norman Hansen