chips

# Chips Chips are a project's suggested tasks, the side work outside a run's target, or a measurement that does not fit a run's one-hour budget, that the owner can start in a new session. They live as rows in one ledger per project, and a card in a suggest tool is only a view of one. The law is `.agents/pstack/rules/chips.md`, which sync-pstack renders into every project. Read it in full before this session's first ledger write, except in a session a card started, whose brief holds what its own task's rows need. This skill runs its modes; it adds no rule of its own. Every command below is `node .agents/pstack/decisions-check.mjs <command>`, run from the project's checkout, which a card session that opened in its own worktree names by the path its brief prints. In a trunk project, where every session works in its own worktree, every command runs as written from that worktree, because the helper switches to the main checkout on its own for `chips` and for an `append` to the ledger. Get this session's id from the runtime's session tool, such as Claude Code desktop's `get_session` with `self`, and pass `--session <id>` to every board read. A runtime with no session tool reads the board without it. | Mode | Use it to | | --- | --- | | [Sweep](#sweep), `/chips` with no argument, `/chips all` or `/chips codex` | bring this session's open tasks up to date, card what can start and report the board; `all` also lists every priority, takes the ship-list tasks and the tasks no live session owns, and merges or separates the tasks `chips groups` pairs across the board, and `codex` forces the Codex handoff on each card it offers, outside trunk delivery | | [Offer](#offer) | add a finding, the one way new work enters the ledger | | [Close](#close) | card the run's own Ready offers at its last hand-back, without the sweep | | [Start](#start) | begin a task a card opened, in the card's session | | [Drop](#drop) | record the owner's word to drop a task | pstack calls these modes too. Where a pstack step files a tracked issue, a follow-up or a reflect Backlog item, or puts an out-of-band fix in its own PR, the lead runs Offer instead for a new P0 or P1 finding, for an item the run's verdict judges or for any finding in a babysit run, and otherwise lists the finding in the plan's Open work, as chips.md's Offer says. It runs a sweep only on `/chips`, and plain words about the whole board run `/chips all`, as chips.md's Sweep says. It runs Close at the last hand-back of a run that offered a task, never after a sweep, whose card pass replaces it. A question about open chips, such as "what's next" over side work or whether a chip is still worth doing, runs step 1's `chips` and `chips stale` reads without `setup.mjs` or the cleanup, judges each task it asks about as step 3 does, its companion fetch included, and answers in step 6's shape, logging no row and offering no card; its answer names the row step 3 would log and says which sync of the ledger it read, such as the one this session's start-up hook ran, because a question runs no `setup.mjs` of its own. ## Sweep 1. In a trunk project, first run `node .agents/pstack/setup.mjs` from the main checkout, which fast-forwards it when no local edit is in the way. Run `chips --session <id>` and `chips stale`. The stale report lists each open task with its age, its priority, a ship item that closed, the paths it writes that were deleted since its offer or are missing, the commits on its paths since its offer, its closed PR waits, its card and whether it lacks the review scope chips.md's Milestone asks for, the likeliest stale first. Then clean up the card sessions of landed tasks, as chips.md's Cleanup says. Save the session tool's list of every session, archived ones included, such as Claude Code desktop's `list_sessions` with `include_archived` and a `limit` above the session count, as a JSON array in the run directory, and run `chips cleanup --sessions <file> --session <id>`. For each session it lists under Archive or Keep, read that session's last report with the session tool and fix each piece of workflow friction the report leaves unsettled, as chips.md's Landing says. Then archive each session it lists under Archive, save the list again, run `chips cleanup` again and run the `scan.mjs --remove` command it prints. Keep the first run's Report lines for step 6. Under `/chips all`, read the board again with `chips all --session <id> --sessions <file>`, using the list saved last, as chips.md's Owner says, and use that board from here on. A runtime with no session tool skips this, keeps the board `chips` printed without `--session`, because `chips all` needs one, and limits the sweep as chips.md's Limits says. 2. Apply the pass the Do list shows, together with the run's own rows that chips.md's Sweep lists, in one `append --from <file>` batch: - Withdrawal pass: call the dismiss tool on each card it names, then log the row the tool's report decides, as each item says. - Ledger pass: log each row it names, after checking the pair of a merge or fold item against chips.md's dup bullet, as its Sweep says. For a prioritize item, judge the task's priority from its brief as chips.md's Priority says, and check that a bug's repro still fails before you claim P0 or P1 for it. For a ship item, append the offer it prints, adding to its tokens the `review-scope:` that chips.md's Milestone gives. - Card pass: leave it to step 5. - Check items: look each session up with the session tool, read the last report of each archived one, and log the row chips.md's Sweep gives for it. A task the tool cannot settle stays started, and step 6 says why. Run the same board read again, `chips all --session <id> --sessions <file>` under `/chips all` and `chips --session <id>` otherwise, and repeat until the Do list shows only the card pass or nothing you can apply. When `append` refuses a batch, fix or drop the refused row as its message says and append the rest. 3. Judge each task the stale report gives a fact, from its brief, those facts and the code, and append the rows in one batch: - When the tree already holds its fix, log `dismissed done`, citing the commit. For a task that writes only in another checkout, cite that checkout's commit and the project commit that synced it, as chips.md's `landed` row does. - When its target was deleted since its offer, log `dismissed superseded` only once the companion repository, when the project has one, tracks it neither in the checkout nor on its fetched `origin/<branch>`. `chips stale` reads a move as a delete when its halves landed more than a day apart or the move changed the file. `setup.mjs` also fast-forwards only the project's branch, so the checkout's companion can lag its origin. When the companion tracks the target now at the same path, the path is still right, so log nothing for it. When a path only moved, log `updated` with the new `writes:`, or for a carded task leave the new path to its session's `started` row, as the next bullet says. When one path it writes was deleted and its target lives on, log `updated` without that path. - A missing path is one the offer named wrongly or one the task will create. Find the real path with `git ls-files`, and with the companion repository's own `git ls-files` when the project has one, because the project's git ignores the files the companion tracks, and log `updated` with it, or leave a path the task creates. A path in another checkout that this machine lacks stays as it is, because the ledger syncs to every clone. A carded task's `updated` only drops paths, so its session names the real one in its `started` row. - When a PR it waits on closed without merging, log `updated` with the waits it has now. - When two open tasks answer one question, log the topic move and `dismissed dup` that chips.md's Sweep gives, and `updated` on the kept task with the review scope and regression pages that chips.md's Milestone gives for the work of both, when the duplicate's differ. They answer one question only when they share two kinds of evidence, as chips.md's Groups bullet names them, and one fix removes both; similar wording alone never does. When the keeper holds a card or is started, log `updated` on the other with its waits plus `task:<keeper>` instead, with the keeper's topic too when the keeper holds a card in another topic. Log nothing for two design questions in different topics while that card lasts, as chips.md's dup bullet says. When the other holds a card this session cannot withdraw, log `updated` on the keeper with its waits plus `task:<other>`, and with the other's topic when the topics differ, so the keeper gets no second card. Two design questions in different topics take no such row. - For a started task, log `landed` when a commit holds its change. Step 2's check item settles the rest from its session, so never ask the owner whether that session still runs. - When the report marks a task possibly thin, find its finding in the plan, log or run its offer names, and log it as a `folded` row. When this session holds the task's card, withdraw it first. When another session holds it, fold the finding once that card leaves the queue. When no source holds the finding, leave the task as it is. Step 6 says which tasks stay thin. - When the report says a task has no review scope and step 2 left it offered, log `updated` with the `review-scope:` that owns the code it writes, or `none` when no review scope does. For a task that came from a triaged issue, copy the record's `scope:` and its `regression:`, as chips.md's Milestone says. When a task's facts tie it to several scopes, pick the one chips.md's Milestone gives. When a copied record's `priority:` is above the task's, give that priority too, as chips.md's Milestone says. - Judge the dependencies and effort of each task that holds a card, as chips.md's Cards says. - Judge each offered task's own priority again against chips.md's Priority, because an `updated` row on a started task takes only `owns:`, `review-scope:` and `regression:`; the stale report prints it as `own` when a waiting task raises it. Log `updated` with the right `priority:` and its evidence when it differs. When the report says a task's ship item closed, log `dismissed done` when the item's work landed, or `updated` with the priority its work has now. - Under `/chips all`, once you have appended these rows, run `chips groups` and judge each pair it lists as chips.md's Groups bullet says, whatever session owns each task. When one fix removes both, settle them as chips.md's dup bullet says. When another session holds the duplicate's card, log nothing on the duplicate, and give the task it duplicates the wait chips.md's dup bullet gives. When both are started, name the pair in the report. Otherwise log `apart` with `from:`, then `updated` with an offered task's waits plus `task:<id>` when it needs the other's result, or on the later one when one fix removes both but they share only one kind of evidence. When both are design questions in one topic and neither needs the other's result, also give the later one a topic of its own, or the earlier one when another session holds the later one's card, as chips.md's Groups bullet says. Append those rows in one batch. 4. Repeat step 2 for what step 3 changed. 5. Card pass: before each card, judge the task's dependencies and effort as chips.md's Cards says. Then offer each card the Do list names with what `chips brief <id>` prints as its prompt, verbatim, the brief's first line as its title, which starts with the task's priority such as `[P0]`, shortened to fit the tool's title limit with that priority and any `(xhigh)` or `(fast)` kept, the effort its brief shows and its own worktree, such as `start_session`'s `use_worktree: true`, because the tool's default shares this session's folder when this session did not start in a worktree, all in the same turn, then log `carded` with `card:` and `session:`, plus `codex: always` under `/chips codex` outside trunk delivery. A runtime with no suggest tool lists each Ready task in the plan's `## Open work` instead, or in the reply when the run keeps no plan, as chips.md's Limits says. Before each card, check whether the task's `writes:` touch an active plan, one whose `Status:` starts with a word `status.mjs` counts as active, such as building. That plan's files are the plan itself, its decision log and its subject file `<plans>/topics/<topic>.md`. The topic is its `Topic:` line, or the first entry of the frontmatter list that `pageTopic.field` in `.agents/pstack.json` names. Its session is rewriting those files, and `chips` sees only ledger tasks, so log `updated` with the task's waits plus `run:<that plan>` instead of the card. 6. Report first the cleanup's Report and Keep lines, each task the sweep cleaned up with its commits, and each worktree `scan.mjs --remove` kept with its reason. Then report in plain words each row this sweep logged, one line each, then what can start and whether it has a card, with `start <id>` beside each Ready task the 10-card limit left uncarded, what is started, why it stays open and that "drop <id>" closes it, what waits and on what, grouped by the thing waited on, and the fast work owed a review. When a task waits on landed work the owner has not committed, the report suggests that commit before it lists what can start, naming each landed task and how many waiting tasks its commit frees, because those tasks can start only after it. Name each task by id and title. The report names each commit by its subject and ends with its links, the cleanup lines' links included, as writing.md's Links in replies rule says, with the owner and repository read from the checkout's `origin` remote. The report asks the owner nothing. When a session's report or its plan holds a question for the owner, the lead settles it. It answers from the law that governs the question in a message to that session, which logs the answer as a `look` Defaults row and a decision row in its own plan, because that session owns the plan's files. When that session is archived or gone, the lead logs both rows itself. When no law answers it, the lead offers it as a `decide` task when it is P0 or P1, and otherwise lists it in the report, as chips.md's Offer says for a run that keeps no plan. The owner reverses a dismissal by asking. The lead logs `reopened` on a duplicate, as chips.md's `reopened` row says, and offers any other task again where chips.md's Offer allows it, or else lists it in the report. ## Offer Offer only a new P0 or P1 finding, unless it is an item the run's verdict judges, a finding in a babysit run or a measurement the Time budget rule sends here, as chips.md's Offer says. List any other finding in the plan's Open work, or in the reply when the run keeps no plan. A project hook that finds recurring work due offers its own P2 or P3 task with `via: hook` without this mode, and the session it stops runs [Close](#close) on that task. 1. Run `chips --session <id>` first, and read the brief of each open task whose topic or title touches the finding with `chips brief <id>`. 2. Pick the row as chips.md's Offer says: - When the finding belongs to an offered task's question and that task holds no card, log a `folded` row on it with what the finding adds. - When it belongs to the question of a started task or of one that holds a card, with two kinds of evidence and one fix that removes both, as chips.md's dup bullet asks, offer a new task in that topic with `waits: task:<id>`. `chips` merges it into a carded task once the card is withdrawn. - Otherwise offer a new task with an id from `chips id`, a plain imperative title, `(xhigh)` only where chips.md's Title rule gives it, and its `writes:`, `topic:`, `kind:`, `priority:` with the evidence chips.md's Priority asks, `via:` on a P2 or P3 offer, `review-scope:` and `regression:` where chips.md's Milestone asks for them, `waits:`, `owns:` and `session:`, this session's id, which makes it this session's task, as chips.md's Owner says. Its `waits:` include `run:<plan>` for each active plan whose files it writes, as Sweep step 5 finds them. Reuse a topic the board lists when the finding answers its question. A new topic names one owner question, never an area. 3. Append it with `append <ledger> chip "<id> <title>" "<finding>" "<tokens>" <result>`, where `<ledger>` is `<plans>/artifacts/suggested-tasks.decisions.tsv` in trunk delivery and `<plans>/suggested-tasks.decisions.tsv` otherwise, the path chips.md's Ledger names. When `append` refuses the row, its message names the route; follow it. 4. Card it in [Close](#close) at the run's last hand-back, not now, because a later finding in this run may still fold into it, and a carded task takes no `folded` row. ## Close A run that offered a task runs this at its last hand-back, once it has delivered its work, closed its plan and made its last offer, reflect's included, as chips.md's Close says. A session a card started runs it too, after its friction fixes and before `scan.mjs --landed`, as chips.md's Landing says. 1. Run `chips brief <id>` for each task this run offered, whose `State:` line says at any priority whether it is Ready and what it waits on, and read no board, because a board's card pass lists tasks this run did not offer. For each task this run offered that is Ready, judge its dependencies and effort as chips.md's Cards says. For a task that needs another open task's result, log an `updated` row with its waits plus `task:<that id>` in place of its card, after an `apart` row naming that task when the two share a topic and are no duplicate, as chips.md's Cards says. A task whose brief says it was merged into another task gets no card, because the kept task's owner session cards the kept task. Append these rows in one batch before any card, because a new wait can raise the priority the next brief prints, and a card's title cannot change. 2. Offer a card for each of the rest that is not deferred, the way Sweep step 5 offers one, highest priority first, within the 10-card limit and all in one turn. A deferred task waits for `/chips`, which cards it after every task that ranks above it, as chips.md's Deferred says. Then append each card's `carded` row in one `append --from` batch. 3. Leave every other task to `/chips`. 4. Add one line to the reply just above its links: how many tasks the run offered, how many it carded and what each of the rest waits on, or that it is deferred, with `start <id>` beside each Ready task the limit left uncarded. `/chips` cards a waiting task once its wait clears, or `/chips all` for a ship-list task or once this session is gone. A runtime with no suggest tool still runs step 1, then lists each Ready task in the reply instead of carding it, as chips.md's Limits says for a plan that has closed, and leaves step 4's `/chips` and `/chips all` hints out, because they card nothing there. ## Start A session a card opened, or one the lead started on the owner's "start <id>", runs this before it writes anything, as chips.md's Sweep says. 1. Run `chips brief <id>` and work from what it prints, not from the card's prompt. 2. When the brief's `State:` line says neither Ready nor Started, tell the owner what it says and stop. 3. Log `started` with `writes:` naming any path the brief lacks and `session:` naming this session's id where the runtime's session tool gives one, then run `chips brief <id>` again, because the task could change until that row. When the session tool shows this session above the brief's `Effort:`, say so to the owner in your first reply, because a session cannot lower its own effort. 4. Before writing a path the task does not list, log another `started` row with it. When `append` refuses that row because another started task writes that path outside the checkout, which happens only outside trunk delivery, leave the path alone and tell the owner. 5. When the work is done, land it and log `landed`, then fix the workflow friction you hit as the brief says, then run [Close](#close) on each task you offered, then remove the worktree as the last command, as the brief's paragraph on landing and chips.md's Landing say. A review task's session first logs `reviewed` on each task it reviewed. ## Drop 1. When the task is started, log `dismissed stopped`. 2. When the task holds a card this session offered, call the dismiss tool on it. When the tool reports the owner started it, log `started` and tell the owner. Otherwise log `dismissed declined` with its `card:`, in place of `uncarded`, so no merge lands between the two. 3. When another session holds its card, log `dismissed declined` with that `card:`. 4. When it holds no card, log `dismissed declined`.