Skip to content

Document kickstart silent exit and land handoff #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
bpmooch wants to merge 1 commit into from
Closed

Document kickstart silent exit and land handoff #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 13 additions & 6 deletions src/content/docs/dn/completing-github-issues.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,13 +81,15 @@ the branch and pull request provide enough isolation for review.
## Complete and verify work locally

Run `kickstart` without a publish mode to keep the plan and changes in the
current workspace:
current workspace. Attended kickstart exits after success — it does not close
the GitHub issue or ask whether to continue:

```bash
dn kickstart 123
dn until validate .github/dn/gambit.json
dn until run .github/dn/gambit.json
dn land --issue-testplan
dn todo done 123
```

Configure the gambit so its generator resolves problems in the current issue
Expand Down Expand Up @@ -116,9 +118,12 @@ generator and verifier within the configured budget, leaving all work local.
Review the resulting diff before running `land`.

`land` validates the completed plan, groups the workspace changes into local
commits, and removes the plan. `--issue-testplan` also upserts a concise
`## Test Plan` checklist on the linked issue. It does not push or open a pull
request.
commits, and removes the plan. It targets **one plan at a time** (explicit path,
`PLAN`, or newest `plans/*.plan.md`). Do not stack multiple local kickstarts
before landing — use `--publish pr|direct` when you want each issue published
without a separate land step. `--issue-testplan` also upserts a concise
`## Test Plan` checklist on the linked issue. It does not push, open a pull
request, or close the issue.

Push the resulting feature branch or bookmark with your usual VCS workflow, then
open the pull request:
Expand Down Expand Up @@ -240,8 +245,10 @@ dn kickstart --publish pr --milestone 42 --complete

`dn init stack` scores and orders the open issues. `--once` processes the next
unchecked item and is suitable for CI. `--complete` processes every remaining
item. Use `--publish pr` in an ephemeral runner so each completed issue produces
a durable pull request.
item and **requires** `--publish pr` or `--publish direct` so each stack item is
published before the next. Use `--publish pr` in an ephemeral runner so each
completed issue produces a durable pull request. On `--once` / `--complete`
success, the stack item is marked done and the GitHub issue is closed.

To clarify the milestone outcome before creating its execution queue, run:

Expand Down
5 changes: 3 additions & 2 deletions src/content/docs/dn/filesystem-context.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,8 +127,9 @@ This produces:
- `plans/{owner}_{repo}_{milestone}.stack.json` — machine-readable queue state

Commit both files when you want the queue tracked in version control. Run
`dn kickstart --milestone 42` to work through unchecked items; use `--complete`
to drain the queue without prompts between tasks. See
`dn kickstart --milestone 42` to work through unchecked items; use
`--publish pr --complete` to drain the queue without prompts between tasks (each
item is published before the next). See
[Completing GitHub Issues](/dn/completing-github-issues/#milestone-queues).

## Project base images
Expand Down
11 changes: 8 additions & 3 deletions src/content/docs/dn/task-list-and-sync.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,9 @@ dn todo done plans/auth.plan.md
```

When the ref is a GitHub issue, `dn` closes the issue with a comment. Use this
after work lands to keep the list and GitHub in sync.
after `dn land` (or after `--publish direct` when you want the issue closed) to
keep the list and GitHub in sync. Attended `dn kickstart` does not mark todo
items done on exit.

## `dn tidy`

Expand All @@ -97,8 +99,11 @@ running the top item. If the list is empty, it can search the current repository
for open issues and plan files, score them, write the list, and suggest the
first item.

After a successful run, `dn` can mark the item done and continue to the next
one.
Attended kickstart exits after a successful run. It does not mark the queue item
done or ask to continue. Review the changes, run `dn land` when you are ready to
commit, then `dn todo done` to check the item off and close the GitHub issue if
applicable. For per-issue publish without a separate land step, use
`--publish pr` or `--publish direct`.

## `dn sync`

Expand Down
9 changes: 6 additions & 3 deletions src/content/docs/dn/workflows.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,9 @@ dn land plans/issue-123.plan.md --dry-run

`land` discovers or accepts a `plans/*.plan.md` file, verifies its checklist,
reviews current workspace changes, and uses the selected agent to group them
into logical conventional commits. On success, it removes the plan file.
into logical conventional commits. On success, it removes the plan file. Land
targets one plan at a time; for per-issue publish without stacking local
kickstarts, use `dn kickstart --publish pr|direct` instead.

`--single` creates one deterministic commit without an agent. `--dry-run`
previews the operation without committing, deleting a plan, or changing GitHub.
Expand Down Expand Up @@ -318,12 +320,13 @@ the gambit file.
dn meld --milestone 42
dn init stack 42
dn kickstart --milestone 42 --once
dn kickstart --milestone 42 --complete
dn kickstart --publish pr --milestone 42 --complete
```

`dn meld --milestone` writes a user-value-focused milestone description.
`dn init stack` creates a prioritized execution queue. `--once` processes one
unchecked item; `--complete` processes all remaining items.
unchecked item; `--complete` processes all remaining items and requires
`--publish pr` or `--publish direct`.

## `dn sync`

Expand Down
Loading