feat: /awos:quick — ad-hoc task shortcut outside the spec cycle - #171
feat: /awos:quick — ad-hoc task shortcut outside the spec cycle#171kdementiev-provectus wants to merge 8 commits into
Conversation
Adds a shorter path for contained, one-off work that needs a plan and a specialist but not a full spec → tech → tasks → implement → verify cycle. Like /awos:implement, it is an orchestrator only — it plans a single task, delegates the coding to a specialist subagent (the same specialists /awos:implement uses), and never writes code itself. Depth is asked up front (plan-only / discuss / research / full) rather than via flags, and it asks before committing. Quick tasks are tracked in context/quick/, separate from context/spec/ and the roadmap, with list/status/resume subcommands. - commands/quick.md — full command prompt (ROLE/TASK/PROCESS + subcommands) - claude/commands/quick.md — thin wrapper (mirrors description, @-import) - docs/commands/quick.md — command reference doc - README.md — Quick Tasks section under the feature cycle - CLAUDE.md — quick-task shortcut note in the canonical-flow section All 193 markdown/installer tests pass; [email protected] --check clean. Co-Authored-By: Claude Opus 4.8 <[email protected]>
Adds a "When the Full Map Is Too Much" section to docs/rationale.md, extending the zoom-level metaphor to explain when /awos:quick is the right call versus the full vertical cycle. Co-Authored-By: Claude Opus 4.8 <[email protected]>
…, clarify generic-agent selection Three fixes from end-to-end testing of /awos:quick across 10 ad-hoc tasks: 1. Choose the specialist subagent (was Step 6) now precedes writing PLAN.md (was Step 5). PLAN.md requires the **[Agent: name]** marker, so the choice must come first — previously agents had to read ahead or backfill. 2. Step 10 now probes `git rev-parse --is-inside-work-tree` first. In a non-git project it skips the commit question entirely (no git init, changes left on disk) instead of assuming a repo and failing on "Commit now". 3. Step 5 explicitly routes plain config edits, docs, and shell scripts to general-purpose, with a guardrail against forcing a stack specialist just because the verification happens to use its language. docs/commands/quick.md updated to match the reordered flow and non-git behavior. Verified: 193/193 tests pass, prettier clean, and 5 fresh sub-agent runs (git + non-git, python/js/yaml/docs/shell) all completed end-to-end with correct artifacts and the git-repo commit path exercised. Co-Authored-By: Claude Opus 4.8 <[email protected]>
… cases - Add /awos:q as a shortcut alias for /awos:quick - RESUME now runs Step 6.5 (project context) before delegation - RESUME handles missing PLAN.md and already-complete tasks gracefully - Switch head -1 → tail -1 in STATUS/RESUME to pick most recent match - Specify disambiguator format (-2, -3) for duplicate slugs - Add tiebreaker rule for agent selection (prefer narrower specialist) - Clarify LIST date logic (YYYYMMDD prefix, not filesystem timestamp) - Add DRY Validation and missing steps to docs Co-Authored-By: Claude Opus 4.6 <[email protected]>
|
Warning Review limit reached
Next review available in: 44 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (6)
📝 WalkthroughWalkthroughAdded ChangesQuick task workflow
Estimated code review effort: 3 (Moderate) | ~20 minutes Sequence Diagram(s)sequenceDiagram
participant User
participant QuickCommand
participant TaskArtifacts
participant SpecialistAgent
User->>QuickCommand: Submit task and execution depth
QuickCommand->>TaskArtifacts: Create task directory and PLAN.md
QuickCommand->>SpecialistAgent: Delegate plan, context, and scope
SpecialistAgent->>TaskArtifacts: Write SUMMARY.md and verification evidence
QuickCommand->>User: Report outcome and commit state
Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Co-Authored-By: Claude Opus 4.6 <[email protected]>
The lint suite requires every wrapper in claude/commands/ to have a matching file in commands/. Added commands/q.md as a redirect to quick.md with the required INTERACTION section markers. Co-Authored-By: Claude Opus 4.6 <[email protected]>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@commands/quick.md`:
- Around line 157-160: The delegation guidance in the Agent workflow must add a
completion check after each Agent return: require the coordinator to inspect the
specialist’s fresh verification output and spot-check the reported files before
accepting success, matching the minimal check in the implement flow for every
depth. Preserve Step 8 as the additional Full validation rather than replacing
it.
- Line 43: Define an explicit fallback for an empty or skipped task description
in Step 0 before entering RUN, such as retaining the documented default task
behavior or stopping with a clear prompt; ensure slug generation receives a
valid task prompt and remains consistent with the no-stop rule for other
unanswered questions.
- Around line 54-55: Update the route descriptions for STATUS and RESUME in
commands/quick.md so the trailing separator space is outside each inline code
span, preserving the documented command syntax and wording.
- Around line 161-162: Update the delegation-failure handling in the “Wait for
the subagent to report completion” step to write a SUMMARY.md with status:
incomplete and the failure details before stopping. Ensure the existing
stop-and-surface behavior remains, and make the summary available for LIST and
STATUS classification.
- Around line 77-80: Reorder the task setup instructions so the collision check
and resume/disambiguation flow occur before directory creation. Update the steps
around “Generate a slug,” the duplicate check, and “Create the directory” to
check the candidate slug first, preserve the RESUME option, append a numeric
disambiguator until unique when requested, then create only the final resolved
directory.
In `@docs/commands/quick.md`:
- Around line 66-82: Change the Markdown code fence surrounding the AWOS
slash-command examples in the documented quick-command section from bash to
text, leaving the examples and their leading > prompts unchanged.
In `@docs/rationale.md`:
- Line 47: Update the user-facing documentation text at the relevant location to
use “bug fix” instead of “bugfix,” preserving the surrounding sentence and
formatting.
In `@README.md`:
- Line 65: Update the `/awos:quick` depth label in the README description from
“plan-only” to the available “Plan and execute” label, while preserving the
other listed options and the command’s documented workflow.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 1ace94bb-bf38-4b18-936a-e44de22cee3f
📒 Files selected for processing (7)
CLAUDE.mdREADME.mdclaude/commands/q.mdclaude/commands/quick.mdcommands/quick.mddocs/commands/quick.mddocs/rationale.md
- Add completion check after Agent returns (inspect evidence before accepting success) — matches /awos:implement's minimal check - Reorder Step 2: collision check before mkdir (already done, was in prior commit but CR reviewed older diff) - Write SUMMARY.md with status: incomplete on delegation failure (already done, same as above) - Empty prompt fallback already handled in INTERACTION section - Change docs code fence from bash to text for command examples - Fix "bugfix" → "bug fix" in rationale - Fix "plan-only" → "Plan and execute" in README depth labels Skipped: trailing space in `status ` / `resume ` route patterns is intentional — the space is the delimiter between the keyword and the slug argument. Co-Authored-By: Claude Opus 4.6 <[email protected]>
AlexanderMakarov
left a comment
AlexanderMakarov
left a comment
There was a problem hiding this comment.
Before the inline details — I'd push back on the premise itself, on three grounds.
First, this grows the core surface. A new core command is cognitive load for every AWOS user — the README now offers built-in plan mode, /awos:quick, and the full cycle for overlapping classes of work, with the choosing burden on the user — and that cost needs a proportionally strong reason to exist.
Second, the repo already has an answer aimed at exactly this middle: /awos:flow generates a project-tailored /fix-bug command (diagnose → fix → scoped re-verify → targeted spec amendment) — lighter than the spec cycle, delegating to the same hired specialists, and, unlike /awos:quick, ending by amending the specs the change touched. The PR's rationale (full ceremony vs bypassing AWOS is an awkward choice) doesn't engage with that existing path; I'd want it to argue why the flow-generated /fix-bug doesn't cover this, and if a real gap remains (non-bug one-off tasks? projects that haven't run /awos:flow?), whether it's better filled by extending flow's output than by a parallel core command.
Third — and this is the deeper one — /awos:quick writes its PLAN.md/SUMMARY.md to context/quick/, deliberately outside the roadmap and specs. That means the changes it makes are invisible to the product context afterward: the spec documents no longer describe the code, and the SDD premise this whole framework rests on — an agent can rehydrate the project from the documents alone — erodes a little with every quick task. The flow-generated /fix-bug solved this with its spec-amendment step; /awos:quick has no equivalent, and "separate from the roadmap" is presented as a feature. Ad-hoc changes untied to product context are the thing spec-driven development exists to prevent, so if this command ships, it needs a story for how its changes flow back into the specs.
If there's a settled decision behind this I'm not seeing, point me to it and I'll take the premise objection back.
On the implementation itself (details inline):
- Step 6.5 checks a nonexistent path — quick tasks silently never see the architecture doc.
- The slug-lookup glob matches across slug boundaries —
status/resumecan act on the wrong task. - Depth isn't persisted — a resumed "Full" run loses its validation pass.
- The
/awos:qalias never binds$ARGUMENTS. - The PR's new structural contracts (directory layout,
status:frontmatter, delegation-block parity, the quick↔q relation) ship with no Layer-1 pins — nothing fails today, but nothing protects them either.
The rest are small consistency points. The CodeRabbit round is fully addressed — nothing from it re-raised here.
| Check which AWOS context files exist in the project: | ||
|
|
||
| - `context/product/product-definition.md` | ||
| - `context/architecture/architecture.md` |
There was a problem hiding this comment.
This path never resolves — the architecture doc lives at context/product/architecture.md (that's what commands/architecture.md, tech.md, and hire.md all read and write; nothing in the repo creates context/architecture/). As written, the existence check silently fails and the subagent never sees the architecture, which quietly defeats the "stays aligned with the project's design" promise the README makes for this command. RESUME step 5 reuses this list, so it inherits the same miss.
|
|
||
| 1. Generate a slug from the task description (per Slug rules). | ||
| 2. Compute today's date: `date +%Y%m%d`. | ||
| 3. Check for collisions: `ls -d context/quick/*-[slug]/ 2>/dev/null`. If a match exists, ask the user whether to resume it (go to **RESUME**) or append a numeric disambiguator (`-2`, `-3`, etc.) to the slug until unique. |
There was a problem hiding this comment.
Two things on this collision check:
- The glob
context/quick/*-[slug]/isn't anchored to the date prefix, so*can eat across slug boundaries — with an existing20260101-fix-auth-bug, creatingauth-bugfalse-fires a collision, andstatus auth-bug/resume auth-bug(lines 230 and 240 use the same pattern) silently return the wrong task instead of "not found".context/quick/????????-[slug]/(exactly eight date characters) fixes all three sites. - The resume-vs-disambiguate choice here is a fixed two-option ask written as prose — elsewhere in this file (depth, commit, re-run) you route those through
AskUserQuestion; this one could match.
| 4. Announce what you're resuming and the current status. | ||
| 5. Run Step 6.5 (Gather Project Context) to check for AWOS context files — resumed tasks still need project alignment. | ||
| 6. Extract the agent name from `PLAN.md`'s `**[Agent: agent-name]**` field. If the field is missing, fall back to Step 5 (Choose the Specialist Subagent) before delegating. | ||
| 7. Continue from where the task left off: re-enter the RUN flow at Step 7 (Delegate Execution) using the existing `PLAN.md`, passing the subagent the plan plus a note of what remains. Then finish with Steps 8–11. |
There was a problem hiding this comment.
Step 8 is gated on "If depth is Full", but depth only exists in Step 1's interactive choice — the PLAN.md schema doesn't persist it, so when RESUME re-enters here and "finishes with Steps 8–11" there's nothing to evaluate, and a "Full" run that gets resumed silently loses its validation pass. Persisting a Depth field in PLAN.md next to the Agent field (and reading it back in RESUME), or an explicit resume default, would close it.
|
|
||
| Follow the full process defined in `.awos/commands/quick.md` — this command is identical in every way. | ||
|
|
||
| Read the file `.awos/commands/quick.md` and execute it exactly as written, passing through the user's prompt unchanged. |
There was a problem hiding this comment.
This file never binds $ARGUMENTS — every other root command anchors user input with <user_prompt>$ARGUMENTS</user_prompt> (implement.md:19, spec.md:29, tasks.md:21…). Without the placeholder, the host appends the typed text to the end of the prompt, and the runtime Read of quick.md then surfaces a literal, unsubstituted $ARGUMENTS for Step 0 to route on — it mostly works by model goodwill. A one-line - **User Prompt:** <user_prompt>$ARGUMENTS</user_prompt> makes it mechanical.
Separate question, genuinely asking: is the runtime-Read alias (vs the @.awos/commands/… import the wrappers use) deliberate — nested @-imports not resolving? If so, a one-line note here would keep the next editor from "fixing" it.
| # INTERACTION | ||
|
|
||
| - Use the `AskUserQuestion` tool for multiple-choice questions instead of plain text or numbered lists. | ||
| - An unanswered or skipped question is never a stop signal — in an unattended run, fall back to the documented default and continue, including writing the task's `PLAN.md` and `SUMMARY.md`. The default depth is "Plan and execute"; the default commit choice is "Don't commit". |
There was a problem hiding this comment.
This sentence deliberately mirrors the deliverable-command contract the linter enforces ("never a stop signal" + "including writing"), but quick.md isn't added to the deliverableCommands array in tests/lint-prompts.test.js (~line 421) — so the contract is unenforced and free to drift. Adding 'quick.md' there passes immediately. (The other new contracts worth pinning are in the summary.)
| 2. For each directory, derive: | ||
| - **slug** — the directory name with the `YYYYMMDD-` prefix stripped. Before displaying, sanitize: strip non-printable characters and path separators. Never interpolate a raw directory name into a shell command. | ||
| - **date** — from the `YYYYMMDD-` prefix in the directory name. | ||
| - **status** (determined by comparing the `YYYYMMDD` prefix to today's date): |
There was a problem hiding this comment.
The lead-in says status is "determined by comparing the YYYYMMDD prefix to today's date", but the first two branches read SUMMARY.md and never look at the date — only the two missing-SUMMARY branches do. Worth rewording to "from SUMMARY.md when present, else by age of the date prefix" so a model following the parenthetical doesn't date-classify completed tasks.
| The first four are run once at project setup; the last five iterate per feature. Each command reads/writes a specific document under `context/` (e.g. `context/product/product-definition.md`, `context/spec/NNN-feature/tasks.md`). The numeric prefix on spec directories is allocated by `scripts/create-spec-directory.sh`. | ||
|
|
||
| **Implementation delegation rule:** `/awos:implement` is an orchestrator only — it reads `tasks.md`, extracts the `**[Agent: name]**` marker from each task, and delegates to a subagent. The orchestrator is explicitly prohibited from editing code itself. Preserve this contract when editing `commands/implement.md`. | ||
| **Quick-task shortcut:** `/awos:quick` sits alongside the canonical flow for contained, one-off work that doesn't justify a full spec. It plans a single task, delegates to a specialist subagent, and writes `PLAN.md`/`SUMMARY.md` under `context/quick/NNNNNNNN-slug/` — separate from `context/spec/` and never tracked in the roadmap. It shares `/awos:implement`'s orchestrator-only contract (delegates all code changes) and offers `list`/`status`/`resume` subcommands. |
There was a problem hiding this comment.
NNNNNNNN-slug reads as an eight-digit sequence number — especially two paragraphs after the spec NNN- prefix convention — but it's a date. context/quick/YYYYMMDD-slug/, as the other docs write it, avoids the misread.
|
|
||
| ### Quick Tasks | ||
|
|
||
| For contained, one-off work that needs a plan and a specialist but not a full spec — a focused bugfix, a small refactor, a config or dependency change — use the shorter path: |
There was a problem hiding this comment.
The tip a few lines up still says "Hotfixes, simple bugfixes, and small edits" belong to built-in plan mode, and this section now routes "a focused bugfix" here — opposite advice in adjacent paragraphs. commands/quick.md's WHEN TO USE already draws the three-way line (trivial one-step edit → plan mode; needs a plan and a specialist → quick; roadmap feature → full cycle); narrowing the tip to that framing would make the README agree with itself.
|
|
||
| Nothing in `context/spec/` or the roadmap is touched. | ||
|
|
||
| ## When to use it |
There was a problem hiding this comment.
All nine existing docs/commands/*.md pages carry ## Prerequisites right after "What it does". It's genuinely informative here too — quick is the one command that works with zero prerequisites, using the context files only when they exist.
| - Starts with `list` → go to **LIST**. | ||
| - Starts with `status ` → the remainder is a slug → go to **STATUS**. | ||
| - Starts with `resume ` → the remainder is a slug → go to **RESUME**. |
There was a problem hiding this comment.
These prefixes have no guard: /awos:quick resume the paused ingestion job routes to RESUME, slug-sanitizes the sentence into garbage, and stops with "No quick task found" instead of running the task; list stale feature flags and remove them likewise disappears into LIST. A model will often save this with common sense, but a cheap guard exists: only route to STATUS/RESUME when the remainder already matches the slug rules, and treat list as reserved only when it's the entire prompt — otherwise fall through to RUN.
2 participants
Why
AWOS gives AI agents full project context so they produce correct code — but the full workflow (
spec → tech → tasks → implement → verify) takes five steps. That's the right investment for a roadmap feature, but overkill for everyday work: fixing a bug, tweaking a config, or doing a small refactor.Without a lighter option, teams face an awkward choice: run the full ceremony for a 20-minute fix, or bypass AWOS entirely and lose the quality guarantees (a written plan, a matched specialist, alignment with architecture).
/awos:quickis the middle path. One command that still plans before coding, still picks the right specialist agent, and still reads the project's product definition and architecture — but skips the layers a small task doesn't need.Summary
/awos:quick— a single command for contained, one-off work that doesn't justify a full spec cycle./awos:implement), and recordsPLAN.md+SUMMARY.mdundercontext/quick/.product-definition.md,architecture.md,roadmap.md) before execution — so even quick tasks stay aligned with the project's design decisions.list,status <slug>, andresume <slug>subcommands for task management.context/spec/and the roadmap — quick tasks never pollute the feature backlog.Usage examples
What's included
commands/quick.mdclaude/commands/quick.mdclaude/commands/q.md/awos:qshortcut — points to the same promptdocs/commands/quick.mddocs/rationale.mdREADME.mdCLAUDE.mdDesign decisions
/awos:implement, it never writes code itself. All changes are delegated to specialist subagents.Summary by CodeRabbit
New Features
/awos:quickfor handling focused, one-off tasks through planning, specialist execution, optional validation, and commit confirmation./awos:qand/quickshortcuts.list,status, andresumetask-management commands.Documentation