Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion .claude/rules/prompting.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,4 @@ paths:
- ".claude/skills/**"
---

Before editing these instructions, follow Prompting in `quest context`.
Before editing these instructions, run `quest guide prompting` and follow it.
4 changes: 2 additions & 2 deletions .claude/skills/quest-afk/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: quest-afk
description: Keep quest work moving while the user is away, leaving every decision for their return.
allowed-tools: Bash(quest skill afk) PowerShell(quest skill afk)
---

Run `quest skill afk` and follow its output.
If `quest` is not installed, follow https://github.com/moq-dev/quest/blob/main/SETUP.md first.
!`quest skill afk; echo "If quest skill afk printed an error instead of instructions, install quest as https://github.com/moq-dev/quest/blob/main/SETUP.md describes, then run quest skill afk and follow its output."`
4 changes: 2 additions & 2 deletions .claude/skills/quest-audit/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: quest-audit
description: Audit and fix outstanding quests for disagreements, conflicts, misaligned priorities, and stale plans. Use when the user invokes /quest-audit or asks to audit and fix the quest tree.
allowed-tools: Bash(quest skill audit) PowerShell(quest skill audit)
---

Run `quest skill audit` and follow its output.
If `quest` is not installed, follow https://github.com/moq-dev/quest/blob/main/SETUP.md first.
!`quest skill audit; echo "If quest skill audit printed an error instead of instructions, install quest as https://github.com/moq-dev/quest/blob/main/SETUP.md describes, then run quest skill audit and follow its output."`
4 changes: 2 additions & 2 deletions .claude/skills/quest-complete/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: quest-complete
description: Decide which open PRs to merge, then queue them.
allowed-tools: Bash(quest skill complete) PowerShell(quest skill complete)
---

Run `quest skill complete` and follow its output.
If `quest` is not installed, follow https://github.com/moq-dev/quest/blob/main/SETUP.md first.
!`quest skill complete; echo "If quest skill complete printed an error instead of instructions, install quest as https://github.com/moq-dev/quest/blob/main/SETUP.md describes, then run quest skill complete and follow its output."`
4 changes: 2 additions & 2 deletions .claude/skills/quest-delete/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: quest-delete
description: Abandon a quest.
allowed-tools: Bash(quest skill delete) PowerShell(quest skill delete)
---

Run `quest skill delete` and follow its output.
If `quest` is not installed, follow https://github.com/moq-dev/quest/blob/main/SETUP.md first.
!`quest skill delete; echo "If quest skill delete printed an error instead of instructions, install quest as https://github.com/moq-dev/quest/blob/main/SETUP.md describes, then run quest skill delete and follow its output."`
4 changes: 2 additions & 2 deletions .claude/skills/quest-export/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: quest-export
description: Turn active quests into GitHub issues before leaving Quest. Use when the user invokes /quest-export or asks to export quests before removing Quest.
allowed-tools: Bash(quest skill export) PowerShell(quest skill export)
---

Run `quest skill export` and follow its output.
If `quest` is not installed, follow https://github.com/moq-dev/quest/blob/main/SETUP.md first.
!`quest skill export; echo "If quest skill export printed an error instead of instructions, install quest as https://github.com/moq-dev/quest/blob/main/SETUP.md describes, then run quest skill export and follow its output."`
4 changes: 2 additions & 2 deletions .claude/skills/quest-grill/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: quest-grill
description: Settle open decisions through an interactive interview with the user. Use when the user invokes /quest-grill or wants unsettled thinking challenged before action.
allowed-tools: Bash(quest skill grill) PowerShell(quest skill grill)
---

Run `quest skill grill` and follow its output.
If `quest` is not installed, follow https://github.com/moq-dev/quest/blob/main/SETUP.md first.
!`quest skill grill; echo "If quest skill grill printed an error instead of instructions, install quest as https://github.com/moq-dev/quest/blob/main/SETUP.md describes, then run quest skill grill and follow its output."`
4 changes: 2 additions & 2 deletions .claude/skills/quest-import/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: quest-import
description: Import GitHub issues as quests.
allowed-tools: Bash(quest skill import) PowerShell(quest skill import)
---

Run `quest skill import` and follow its output.
If `quest` is not installed, follow https://github.com/moq-dev/quest/blob/main/SETUP.md first.
!`quest skill import; echo "If quest skill import printed an error instead of instructions, install quest as https://github.com/moq-dev/quest/blob/main/SETUP.md describes, then run quest skill import and follow its output."`
4 changes: 2 additions & 2 deletions .claude/skills/quest-iterate/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: quest-iterate
description: Iterate on an open PR to settle its open decisions, fix CI and review findings, and push.
allowed-tools: Bash(quest skill iterate) PowerShell(quest skill iterate)
---

Run `quest skill iterate` and follow its output.
If `quest` is not installed, follow https://github.com/moq-dev/quest/blob/main/SETUP.md first.
!`quest skill iterate; echo "If quest skill iterate printed an error instead of instructions, install quest as https://github.com/moq-dev/quest/blob/main/SETUP.md describes, then run quest skill iterate and follow its output."`
4 changes: 2 additions & 2 deletions .claude/skills/quest-merge/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: quest-merge
description: Queue a PR to land, running /quest-iterate first when it needs work.
allowed-tools: Bash(quest skill merge) PowerShell(quest skill merge)
---

Run `quest skill merge` and follow its output.
If `quest` is not installed, follow https://github.com/moq-dev/quest/blob/main/SETUP.md first.
!`quest skill merge; echo "If quest skill merge printed an error instead of instructions, install quest as https://github.com/moq-dev/quest/blob/main/SETUP.md describes, then run quest skill merge and follow its output."`
4 changes: 2 additions & 2 deletions .claude/skills/quest-plan/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: quest-plan
description: Scope and create quests through an interactive interview. Use when the user invokes /quest-plan, asks to plan a quest, or wants unsettled work split into quests.
allowed-tools: Bash(quest skill plan) PowerShell(quest skill plan)
---

Run `quest skill plan` and follow its output.
If `quest` is not installed, follow https://github.com/moq-dev/quest/blob/main/SETUP.md first.
!`quest skill plan; echo "If quest skill plan printed an error instead of instructions, install quest as https://github.com/moq-dev/quest/blob/main/SETUP.md describes, then run quest skill plan and follow its output."`
4 changes: 2 additions & 2 deletions .claude/skills/quest-recurring/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: quest-recurring
description: Plan a quest that repeats, such as a periodic audit or a release cut. Use when the user invokes /quest-recurring or wants the same work redone each milestone or release.
allowed-tools: Bash(quest skill recurring) PowerShell(quest skill recurring)
---

Run `quest skill recurring` and follow its output.
If `quest` is not installed, follow https://github.com/moq-dev/quest/blob/main/SETUP.md first.
!`quest skill recurring; echo "If quest skill recurring printed an error instead of instructions, install quest as https://github.com/moq-dev/quest/blob/main/SETUP.md describes, then run quest skill recurring and follow its output."`
4 changes: 2 additions & 2 deletions .claude/skills/quest-review/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: quest-review
description: Review a PR's branch locally with a model that wrote none of it, then mark it ready for review.
allowed-tools: Bash(quest skill review) PowerShell(quest skill review)
---

Run `quest skill review` and follow its output.
If `quest` is not installed, follow https://github.com/moq-dev/quest/blob/main/SETUP.md first.
!`quest skill review; echo "If quest skill review printed an error instead of instructions, install quest as https://github.com/moq-dev/quest/blob/main/SETUP.md describes, then run quest skill review and follow its output."`
4 changes: 2 additions & 2 deletions .claude/skills/quest-spawn/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: quest-spawn
description: Start multiple quests in parallel.
allowed-tools: Bash(quest skill spawn) PowerShell(quest skill spawn)
---

Run `quest skill spawn` and follow its output.
If `quest` is not installed, follow https://github.com/moq-dev/quest/blob/main/SETUP.md first.
!`quest skill spawn; echo "If quest skill spawn printed an error instead of instructions, install quest as https://github.com/moq-dev/quest/blob/main/SETUP.md describes, then run quest skill spawn and follow its output."`
4 changes: 2 additions & 2 deletions .claude/skills/quest-start/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: quest-start
description: Start work on a quest.
allowed-tools: Bash(quest skill start) PowerShell(quest skill start)
---

Run `quest skill start` and follow its output.
If `quest` is not installed, follow https://github.com/moq-dev/quest/blob/main/SETUP.md first.
!`quest skill start; echo "If quest skill start printed an error instead of instructions, install quest as https://github.com/moq-dev/quest/blob/main/SETUP.md describes, then run quest skill start and follow its output."`
4 changes: 2 additions & 2 deletions .claude/skills/quest-unblock/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: quest-unblock
description: Walk the maintainer through every quest and draft PR waiting on them, and clear waits that have resolved.
allowed-tools: Bash(quest skill unblock) PowerShell(quest skill unblock)
---

Run `quest skill unblock` and follow its output.
If `quest` is not installed, follow https://github.com/moq-dev/quest/blob/main/SETUP.md first.
!`quest skill unblock; echo "If quest skill unblock printed an error instead of instructions, install quest as https://github.com/moq-dev/quest/blob/main/SETUP.md describes, then run quest skill unblock and follow its output."`
6 changes: 4 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
Keep the core independent of a particular repository, agent, or issue tracker.

- Read `CONTRIBUTING.md` before making changes or preparing a PR.
- Keep shared engineering rules in `assets/CONTEXT.md`, shared workflow instructions in `assets/AGENTS.md`, and skills in `assets/skills/`, each explaining only its own workflow.
- Keep the rules every task loads in `assets/CONTEXT.md`, within the 10,000 characters Claude Code shows of a hook's context; the workflow sections skills share in the guide, `assets/AGENTS.md`; and skills in `assets/skills/`, each explaining only its own workflow and naming the guide sections and skills it builds on.
- Installing or running a skill never authorizes remote writes or merges beyond the user's request.

Do not edit `CONTRIBUTING.md`, `assets/CONTEXT.md`, `assets/AGENTS.md`, or
`assets/skills/` unless the user asks for that work.

## Development

- Run `quest context` and `quest guide` and read them completely before starting work.
- Read `quest guide` completely before starting work, since this repository develops it.
- Keep README examples consistent with the CLI's actual `--help` output.
In this checkout, `quest` means `bun run --silent quest`; the dev shell's
`quest` is a pinned build for the merge driver, not this checkout.
Expand All @@ -26,3 +26,5 @@ Do not edit `CONTRIBUTING.md`, `assets/CONTEXT.md`, `assets/AGENTS.md`, or
reviews pass.
- Pull requests land as squash merges.
- Do not comment on repositories outside kixelated/moq-dev without approval.

Quests: before any work, run `quest context` and follow it, unless this session already holds its rules.
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,11 +40,11 @@ Quest execution stops at PR creation; it merges only on a /quest-merge pick.
without asking.

On a PR whose author has write access, the PR body's `## Review` record of a
local `quest review` round satisfies the guide's required review when it names
local `quest review` round satisfies the required review `/quest-merge` describes when it names
the exact head being landed, with no finding left unfixed or unrefuted; so does
a recorded skip of a trivial change.
A hand-resolved conflict outside the exemptions below needs a local review of the new head, but does not
require a maintainer review specifically. The guide's exemptions for a
require a maintainer review specifically. `/quest-merge`'s exemptions for a
conflict-free base merge, a reviewer's suggested patch applied unchanged, or a land
fixer's recorded mechanical fix that changes no behavior still apply. Online reviewers' findings already posted are addressed at merge,
never waited for. Dependabot PRs that only bump patch versions or a lockfile
Expand Down
42 changes: 33 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1594,8 +1594,10 @@ then `claude rm` again.
## Work with your agents

Open this repository in Claude Code or Codex. The binary carries the skills;
a repository installs only a stub per skill that runs `quest skill <name>`, so
the version you pin decides what your agents follow:
a repository installs only a stub per skill, so the version you pin decides
what your agents follow. Claude Code's stub inlines `quest skill <name>` when
the skill is invoked; Codex's asks the agent to run it. Either way the skill
arrives with the guide sections and other skills it builds on, in one call:

| Skill | What it does |
| --- | --- |
Expand Down Expand Up @@ -1627,14 +1629,36 @@ Follow https://github.com/moq-dev/quest/blob/main/SETUP.md to set up Quest here.

The [getting started guide](docs/getting-started.md) covers what happens next.

`quest setup` configures your own Claude Code settings for quest work, in
every repository: it sets `env.BASH_MAX_TIMEOUT_MS` to 3300000, so a
foreground command such as `quest wait` can block for 55 minutes, just under
the 1h prompt-cache TTL, instead of the 10-minute default. It edits
`$CLAUDE_CONFIG_DIR/settings.json`, or `~/.claude/settings.json`, keeps your
other settings, prints each setting it changed, and is safe to rerun.
`quest context` prints the rules agents follow in every task, and `quest guide` the
quest format and workflow they read before working on a quest.
quest format and workflow they read before working on a quest outside a skill;
`quest guide prompting` prints one section.

### Configure Claude Code

`quest setup` configures your own Claude Code settings for quest work, in every
repository:

```sh
quest setup
```

It sets `env.BASH_MAX_TIMEOUT_MS` to 3300000, so a foreground command such as
`quest wait` can block for 55 minutes, just under the 1h prompt-cache TTL,
instead of the 10-minute default.

It also loads the rules once. The repository's `Quests: ` line has agents run
`quest context` before any work, which costs a turn and is summarized away
when the session compacts. Instead, `quest setup` installs a `SessionStart`
hook (startup, resume, clear, and compact) and a `SubagentStart` hook, each
running `quest hook`, which adds `quest context` to the session in a
repository whose root `AGENTS.md` or `CLAUDE.md` has the `Quests: ` line, and
nothing elsewhere. `quest` must be on the `PATH` Claude Code starts with, as
for the worktree hooks.

It edits `$CLAUDE_CONFIG_DIR/settings.json`, or `~/.claude/settings.json`,
keeps your other settings, refuses a malformed file unchanged, writes once,
and prints each change. Rerun it after upgrading. `quest setup --remove` takes
the hooks out, and the timeout while it still holds Quest's value.

## Where this is going

Expand Down
26 changes: 18 additions & 8 deletions SETUP.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,13 +44,17 @@ quest init
```

Init writes a stub per skill under both `.claude/skills/` and `.agents/skills/`
without creating symbolic links (existing linked layouts continue to work), creates `quest/README.md` when missing, and appends a line
without creating symbolic links. Claude Code's stub inlines `quest skill <name>`
when the skill is invoked, pre-approving only that command in Bash and
PowerShell, and follows it with a setup pointer for when `quest` is missing; the
`.agents/skills/` stub, which a skill both directories read through a link
gets, asks the agent to run it. Init also creates `quest/README.md` when missing, and appends a line
starting with `Quests: ` to the root `AGENTS.md`, or `CLAUDE.md` when only that
exists. It also appends `quest/** merge=quest` to `.gitattributes` and sets
`merge.quest.driver` in the clone's git config, so local merges resolve
concurrent edits to quest link lists. It writes no Claude Code hooks. It
prints each path it changed and is safe to rerun. Rerun after an upgrade, it
also rewrites the unmodified stubs whose description or setup link changed and
also rewrites the unmodified stubs the new version writes differently and
removes the unmodified stubs of skills the new version no longer ships.

If init refuses, it names the conflicting path. Report it and ask the user how
Expand All @@ -59,11 +63,15 @@ to proceed; never delete or rename their files to get past it.
## Configure the user's agent

`quest setup` configures the user's own Claude Code settings, not the
repository's: it sets `env.BASH_MAX_TIMEOUT_MS` in
`$CLAUDE_CONFIG_DIR/settings.json` (or `~/.claude/settings.json`) to 55
minutes, so agents can block on a long wait in one call instead of polling.
Offer it, explaining that it applies in every repository, and run it with
consent. It keeps the file's other settings and prints what it changed.
repository's, in `$CLAUDE_CONFIG_DIR/settings.json` (or
`~/.claude/settings.json`). It sets `env.BASH_MAX_TIMEOUT_MS` to 55 minutes, so
agents can block on a long wait in one call instead of polling. It also adds
the rules the `Quests: ` line points at to every session and subagent, and
again after compaction, which would otherwise summarize them away, through
hooks that need `quest` on the `PATH` Claude Code runs hooks with. Offer it,
explaining that it applies in every repository the user opens in Claude Code
(the hooks only in those with the `Quests: ` line), and run it with consent. It
keeps the file's other settings and prints what it changed.

## Opt into worktree hooks

Expand Down Expand Up @@ -127,6 +135,8 @@ work or `/quest-import` to bring in open GitHub issues.
chosen Windows install directory). Remove any PATH entry you added. If the
user opted into Quest's worktree hooks and Claude Code no longer finds
`quest`, remove those entries from `~/.claude/settings.json`, since without
it they stop Claude Code making worktrees.
it they stop Claude Code making worktrees. Before removing the binary, run
`quest setup --remove` if the user ran `quest setup` and uses Quest in no
other repository.
4. Ask the user whether to delete `quest/`. Git history keeps the plans either
way.
Loading
Loading