Skip to content

Plan Export - #63

Merged
kubestellar-prow[bot] merged 10 commits into
mainfrom
f-plan-export
Sep 25, 2026
Merged

Plan Export#63
kubestellar-prow[bot] merged 10 commits into
mainfrom
f-plan-export

Conversation

@nicholasjackson

@nicholasjackson nicholasjackson commented Sep 25, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

This PR introduces a new command spektacular plan export and associated capabilities that enable the status of a plan to be exported as json or pretty printed to the terminal. This was requested in #50.

The export shape differs from the original ask in a few places Hive needs to adapt to:

{
  "kind": "plan",
  "name": "000058_plan-task-graph",
  "document_status": "final",
  "tasks": [
    {
      "id": "7c1e4b0a-9d3f-4e2a-8b61-0f5d2c9a7e34",
      "title": "Add the `plan export` command",
      "milestone": 1,
      "repo": { "name": "spektacular", "location": "https://github.com/hivecommons/spektacular" },
      "depends_on": ["0b9f6d2e-5a41-4c7b-9e08-3d1f7a6c2b95"],
      "execution": { "type": "agent", "reason": "" },
      "completed": false
    }
  ]
}
  • --format json is required for this shape. With no --format, the export prints a human-readable view (pretty is the default).
  • id is a UUID, stable for the life of the task. There is no ref; depends_on holds ids, so Hive's ref→id fallback gives matching edges.
  • repo is an object {name, location}, not a string. location is the repo's declared git source; derive owner/repo from it. It is empty when the repo declares no source, and is never guessed from git remote.
    execution is an object {type, reason}, with type either agent or human. Both object fields will fail to decode into Hive's current string fields.
  • completed reflects live progress, and plan status gains per-task progress.
  • spektacular implement can target one task (implement new --data '{"name":…,"task":""}'), so Hive can use Spektacular as its implementation runner. It refuses unknown or completed tasks, tasks with incomplete dependencies, and human tasks. Parallel runs are tracked separately in Parallel implement runs: run independent plan tasks concurrently #62.
  • Plans written before this format are not migrated, and exporting them returns a structural error.

nicholasjackson and others added 10 commits September 25, 2026 11:04
@nicholasjackson
Update ranking constraints test
08eb37a 
Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
@nicholasjackson
Save uncommitted changes before plan workflow for 000058_plan-task-graph
93ebe26 
These are the user's changes from before the plan workflow for 000058_plan-task-graph started. Spektacular committed them separately at the user's request so they are not mixed with the agent's work.

Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
@nicholasjackson
Plan 000058_plan-task-graph: plan task graph, export and single-task …
bdbee4e 
…implement

Plan for spec 000058_plan-task-graph (issue #50), built on the
plan-task-graph design. Four milestones, twelve phases:

- A shared plan task reader and validator; plan.md writes refuse invalid
  task structure; `plan task-id` with a pluggable provider (uuid default);
  milestone commits moved onto the reader.
- `plan export` (pretty/json) and per-task progress in `plan status`.
- Single-task `implement new` with up-front refusals, last-open-task
  wrap-up routing and task-scoped implement instructions.
- Plan workflow authors tasks (phases step renamed to tasks, human-task
  criteria, walkthrough names human tasks), glossary and harbor oracles,
  and public docs for the task format, export and single-task implement.

Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
@nicholasjackson @claude
Plan 000058_plan-task-graph: remove plan working files
d8a110f 
The plan documents are committed to the plan store; the per-section
working files are no longer needed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
@nicholasjackson
Implement 000058_plan-task-graph Milestone 1: plans carry a checked t…
68137d3 
…ask structure

- internal/plantask: one reader for a plan's Milestones & Tasks section
  (ids, repo, dependencies, executor, completion, criteria counts) with
  a validator for the design's structural rules; legacy Phase plans parse
  as their own format.
- plan file write refuses a task-format plan.md that breaks a rule
  (plan_task_invalid, naming the task) before anything is stored; phase
  plans and other plan documents save as before.
- plan task-id issues ids from a pluggable provider
  (plan.task_id.provider, default uuid); unknown providers fail only the
  id request.
- Milestone auto-commits and implement status's unchecked_phases count
  now go through the reader, for task and phase plans alike.

Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
@nicholasjackson
Implement 000058_plan-task-graph Milestone 2: export a plan's task gr…
de3006d 
…aph and per-task progress

- plan export <name> [--format pretty|json] parses plan.md at call time
  and prints the design's grouped text view by default or the JSON task
  graph (kind, name, document_status, tasks with id, title, milestone,
  repo {name, location}, depends_on, execution {type, reason},
  completed). repo.location comes only from a declared git source.
  Unsupported formats, missing plans and plans without task structure
  are refused with structured JSON errors.
- Export and plan status share one document-status computation,
  including strict staleness, so they always agree.
- plan status <name> reports progress {tasks_completed, tasks_total} and
  per-task completion plus acceptance criteria met/total for task plans;
  existing fields are unchanged.

Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
@nicholasjackson
Implement 000058_plan-task-graph Milestone 3: implement one task of a…
eecb385 
… plan on its own

- implement new accepts a task id and refuses, before any state is
  written, a task that cannot start: plan_structure_invalid,
  task_not_found, task_completed, task_dependencies_incomplete (listing
  the open dependencies) and task_requires_human (with its reason).
  implement status and the resume report carry the task.
- A single-task run goes straight from update_changelog to finished
  while other tasks remain open; the run that completes the last open
  task does the test plan, feature changelog and spec reconciliation.
  The new edge is a completion commit point, and completion commits are
  now matched on the step's rendered exit so whole-plan runs are
  unchanged; in full mode they also record any milestone the task closed.
- Implement step templates share a current-task partial: a task run
  names and works on only the selected task, while read_plan still reads
  the whole plan, context, research and designs. Templates, skills and
  partials move to task wording, with a fallback for phase plans.

Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
@nicholasjackson
Implement 000058_plan-task-graph Milestone 4: plan workflow authors t…
196c805 
…asks, feature documented

- The plan workflow's phases step is now a tasks step: ids from
  plan task-id, exactly one repo, explicit Depends on, and Execution
  decided against the four human-task criteria, with mixed work split.
  Scaffolds, assemble, verification and the walkthrough (which names
  every human task before sign-off) move to the task format; the
  spek-plan skill and the managed store-access wording follow.
- Glossary: the phase term is replaced by task.
- Harbor plan-workflow oracles and reference solution move to the tasks
  step and format and check every task's lines and a clean export; both
  plan-workflow (95/95) and implement-workflow (14/14, legacy plan) pass.
- Docs: new Plan tasks page (format, human-task criteria, task ids,
  plan export and every field, progress, single-task implement), linked
  from the nav; How it works and Configuration updated.

Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
@nicholasjackson
Complete 000058_plan-task-graph implementation: test plan, changelog,…
3b4d269 
… spec reconciliation

- Test plan: post-release observation procedures for the four success
  metrics, plus manual checks for splitting mixed work on the reference
  scenario and asking an agent to implement one task.
- Project changelog record plus per-repo records for spektacular and
  docs.
- Spec reconciled: every requirement delivered; three agent-behaviour
  acceptance criteria stay open pending the manual checks.

Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
@nicholasjackson
Update skills for v0.23.0
fdd726a 
Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
@nicholasjackson nicholasjackson self-assigned this Sep 25, 2026
@nicholasjackson nicholasjackson added enhancement New feature or request minor labels Sep 25, 2026
@nicholasjackson

nicholasjackson commented Sep 25, 2026

Copy link
Copy Markdown
Collaborator Author

/approve

@kubestellar-prow

kubestellar-prow Bot commented Sep 25, 2026

Copy link
Copy Markdown

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: nicholasjackson

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow
kubestellar-prow Bot merged commit 2d46ad2 into main Sep 25, 2026
7 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the f-plan-export branch September 25, 2026 11:53
@nicholasjackson nicholasjackson linked an issue Sep 25, 2026 that may be closed by this pull request
Add plan export JSON for downstream stage runners #50
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@nicholasjackson nicholasjackson

Labels

approved dco-signoff: yes enhancement New feature or request lgtm minor size/XXL

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Add plan export JSON for downstream stage runners

1 participant

@nicholasjackson