From 9f88bb70b8f8a8cfed3c1945f44e58661e348202 Mon Sep 17 00:00:00 2001 From: Highbyte Date: Wed, 16 Sep 2026 15:26:52 +0200 Subject: [PATCH] Clarify skill operations, backend support, and worker launch limits --- README.md | 32 +++-- docs/reference/README.md | 10 +- docs/reference/actions.md | 8 +- docs/reference/agent-skills.md | 134 +++++++++++++++--- docs/reference/operator-actions.md | 44 ++++-- docs/reference/web-console.md | 8 ++ docs/workflows.md | 51 +++++-- skills/wrighty/SKILL.md | 7 +- .../wrighty/references/board-and-workers.md | 9 +- skills/wrighty/references/worker-control.md | 38 +++-- 10 files changed, 269 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index f0b7752..189d4ed 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ You use Wrighty from a local directory on your machine that contains the project | Via | What it provides | | --- | --- | -| **Interactively from within an AI agent.** | Use the Wrighty Skill to create, pick, and implement work items. | +| **Interactively from within an AI agent.** | Use the Wrighty skill as a conversational alternative to the web console: summarize work, inspect processing state, manage Local Markdown workflow actions, and start or stop workers. You can also create, pick, and implement items. | | **Wrighty web console.** | Manage, sort, and filter the Local Markdown board; organize operational items and manage settings for both backends. | | **GitHub issues.** | Manage work items if using GitHub backend. | | **Wrighty worker.** | Automatically pick work items, execute them (headless) in a local AI agent, resume work after AI agent usage has expired, or hand off to another local AI agent. | @@ -28,6 +28,13 @@ You use Wrighty from a local directory on your machine that contains the project > - All of Wrighty functionality (worker, web console, skill) is accessed or exposed via the Wrighty CLI app. > - Access to work items is managed via claim tokens to avoid multiple consumers (human/agent/worker/ CLI) working on the same item. +For **Local Markdown**, use the web Board or ask the skill to summarize columns and queue, send +back, or resume eligible items, individually or in reviewed batches. For **GitHub**, plan work in +GitHub Issues and Project views; the skill can summarize those items, but the Board workflow +executors and batches are Local Markdown-only. Processing-state inspection and worker controls +are available through the skill and web **Operations** for both backends. See +[skill capabilities by backend](docs/reference/agent-skills.md#capabilities-by-backend). + ## Where Wrighty has the most impact | Situation | What Wrighty does | @@ -231,12 +238,12 @@ flowchart LR ### Choose your next step -- Follow [Wrighty workflows](docs/workflows.md) to switch safely between the CLI and web console. +- Follow [Wrighty workflows](docs/workflows.md) to switch safely between the skill, CLI, and web console. - Configure a [continuous unattended worker](docs/reference/worker.md) to process a bounded queue. - Use the [GitHub backend](docs/reference/configuration.md#initialize-the-github-backend) when workers need to coordinate across computers. -- Install and invoke the [agent skill](docs/reference/agent-skills.md) for supervised, interactive - work. +- Install and invoke the [agent skill](docs/reference/agent-skills.md) to manage work and workers + conversationally, or implement an item in your current agent session. - Tune model and reasoning choices with [execution profiles](docs/reference/execution-profiles.md). ## Recover a blocked agent without starting over @@ -311,7 +318,8 @@ failure classification, retry schedule, provider circuit, and per-vendor support ## Work with an agent interactively -Install the bundled skill, then invoke it explicitly from your agent: +Use the skill to operate Wrighty from your conversation as well as implement tasks. Install the +bundled skill, then invoke it explicitly from your agent: ```shell wrighty skill install @@ -326,6 +334,8 @@ local installation, or `--scope project` for a deliberate repository-scoped copy /wrighty Pick the next available item, implement it, run its tests, and finish it. # Codex CLI, Desktop, or IDE extension +$wrighty Show my board by status, with counts and item IDs. What needs attention? +$wrighty Which workers are running, and can an existing worker pick up this item? $wrighty Help me turn this feature idea into a well-scoped work item. Show me the proposed title and body before creating it. @@ -335,7 +345,11 @@ title and body before creating it. If a Copilot surface has no skill command, name the Wrighty skill in the prompt. The skill directs agents to mutate tracker state only through the CLI and to branch on structured error codes. See -[Agent skills](docs/reference/agent-skills.md) for per-surface activation and update mechanics. +[Agent skills](docs/reference/agent-skills.md) for backend support, queueing and worker-control +examples, and installation/update mechanics. Worker launch is separate from queueing. The skill +defaults to attached single-item runs; explicitly requested `--max-items` runs are also supported. +Start continuous workers yourself in a terminal or the web console; the skill provides +instructions and can inspect or stop existing runs. It does not keep a worker alive in the background. ## Ownership in four rules @@ -354,8 +368,8 @@ backend, and the lower-level escape hatches. | Topic | Reference | | --- | --- | | Complete behavior reference | [Wrighty reference index](docs/reference/README.md) | -| Workflows end to end (CLI and web console) | [docs/workflows.md](docs/workflows.md) | -| What each action supports in the web console, GitHub, and CLI | [Operator actions by surface](docs/reference/operator-actions.md) | +| Workflows end to end (skill, CLI, and web console) | [docs/workflows.md](docs/workflows.md) | +| What each action supports in the skill, web console, GitHub, and CLI | [Operator actions by surface](docs/reference/operator-actions.md) | | Backends, `wrighty init`, `.wrighty.json` | [Configuration](docs/reference/configuration.md) | | User-scoped settings (`wrighty config`, host label) | [User settings](docs/reference/user-settings.md) | | IDs, create, edit, move, archive, import | [Work items](docs/reference/work-items.md) | @@ -365,7 +379,7 @@ backend, and the lower-level escape hatches. | Choosing a model and reasoning effort per run | [Execution profiles](docs/reference/execution-profiles.md) | | Quota exhaustion, deferred retry, agent handoff | [Usage recovery and agent handoff](docs/reference/usage-recovery-and-agent-handoff.md) | | The web console | [Web console](docs/reference/web-console.md) | -| Skill installation per agent surface | [Agent skills](docs/reference/agent-skills.md) | +| Conversational operations, backend support, and skill installation | [Agent skills](docs/reference/agent-skills.md) | | What is stored where, version control | [Storage and version control](docs/reference/storage.md) | | Physical item metadata per backend | [Item metadata](docs/item-metadata/README.md) | | Architecture and protocol rationale | [Design documents](docs/design/) | diff --git a/docs/reference/README.md b/docs/reference/README.md index 9cd71d6..d839f70 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -13,8 +13,8 @@ first-run guide. These pages are the authority for options, guarantees, and edge - [Claims and ownership](claims.md) — claimant attribution, the ownership rules, fencing guarantees per backend, recovery paths, and escape hatches. - [Action discovery](actions.md) — current actions, blocked alternatives, stable names, and JSON. -- [Operator actions by surface](operator-actions.md) — task-oriented comparison of what the Local - web console, GitHub, and CLI can view or perform, with links to the authoritative procedures. +- [Operator actions by surface](operator-actions.md) — task-oriented comparison of the skill, + web console, GitHub, and CLI, with backend support and links to the authoritative procedures. - [Supported agents and surfaces](supported-agents.md) — which agent families Wrighty supports for skills, headless work, session resume, Desktop opening, and handoff. - [Autonomous worker mode](worker.md) — eligibility, workspace modes, needs-attention and @@ -28,11 +28,13 @@ first-run guide. These pages are the authority for options, guarantees, and edge and opt-in cross-agent handoff. - [Web console](web-console.md) — shared configuration and operations for both backends, plus the Local Markdown board/editor. -- [Agent skills](agent-skills.md) — installing and updating the bundled skill per agent surface. +- [Agent skills](agent-skills.md) — conversational board and worker operations, backend support, + example requests, and installation/update instructions per agent surface. - [Storage and version control](storage.md) — what each backend stores where, and what to commit. Related: [workflow guide](../workflows.md), [item metadata](../item-metadata/README.md), and [design documents](../design/). -- [Worker discovery](workers.md): scoped run inspection and item pickup assessment. +- [Worker discovery and control](workers.md): scoped run inspection, item pickup assessment, + drain, and interrupt. diff --git a/docs/reference/actions.md b/docs/reference/actions.md index dc81582..193386d 100644 --- a/docs/reference/actions.md +++ b/docs/reference/actions.md @@ -15,8 +15,10 @@ reason codes. An optional action name selects one descriptor; an unknown name re Wrighty's normal nonzero exit status and stderr JSON contract. Do not combine a selected name with `--all`. -Discovery is read-only. Queue, Send back, and Resume report `execution: "supported"`; other -catalogue entries remain `manual-only`. Listing an action never claims an item, starts a vendor +Discovery is read-only. On Local Markdown, Queue, Send back, and Resume provide workflow +executors; check each action's availability as well as its execution metadata. On GitHub those +Board actions are unavailable with `NOT_SUPPORTED`. Other catalogue entries remain `manual-only`. +Listing an action never claims an item, starts a vendor session, grants permission, or overrides a pending retry. ## Execute one workflow action @@ -28,7 +30,7 @@ wrighty actions local:42 send-back --exec --yes --json wrighty actions local:42 resume --exec --yes --json ``` -These three executors support Local Markdown and share the web Board's policy and backend +These three executors support Local Markdown only and share the web Board's policy and backend operation. `--exec` requires one action name and cannot use `--all`. An interactive invocation shows the consequence and prompts; redirected input and JSON require `--yes`. This authorizes only the named operation. Neither discovery nor `--yes` grants takeover or starts a worker. diff --git a/docs/reference/agent-skills.md b/docs/reference/agent-skills.md index 168e43c..993591e 100644 --- a/docs/reference/agent-skills.md +++ b/docs/reference/agent-skills.md @@ -1,7 +1,116 @@ # Agent skills -The package contains a narrow `wrighty` Agent Skill shared by Codex, Claude Code, GitHub Copilot, -and OpenCode: +The bundled `wrighty` skill lets you manage work and workers from Codex, Claude Code, GitHub +Copilot, or OpenCode. It is a conversational alternative to the web console for everyday board +and processing operations, and can also help author or implement a work item in the current +agent session. It operates through the Wrighty CLI against the same items and claims as the web +console; switching surfaces requires no synchronization. + +## Capabilities by backend + +Workflow status describes where an item sits in planning. Operational state describes its +processing: for example, an In Progress item may be working, awaiting clarification, or scheduled +to retry. The skill keeps these views separate, just as the web console separates Board from +Operations. + +| Ask the skill to… | Local Markdown | GitHub | +| --- | --- | --- | +| Summarize items by workflow status, including counts and IDs | Yes; a conversational view of the Local Markdown board | Yes; reads tracked issues and configured Project statuses. GitHub Project views remain the planning board | +| Explain processing state, blockers, claims, and available actions | Yes | Yes; exact local session and workspace details require the recording installation | +| Create, inspect, or implement a work item | Yes, through the existing claim-aware CLI workflows | Yes, through the existing claim-aware CLI workflows | +| Queue, Send back, or Resume through the Board workflow executors | Yes, for eligible items | Not supported by these executors; use the appropriate GitHub planning or Wrighty continuation workflow | +| Apply those workflow actions in a reviewed batch | Yes, on the exact frozen selection | Not supported; the skill should explain the limitation without applying a substitute mutation | +| List workers and assess pickup for an item | Yes, within the local configuration scope | Yes, within the local configuration scope; this is not a list of workers on every GitHub-connected computer | +| Start an exact-item, next-item, or bounded queue worker | Yes, when authorized and the host can own the process | Yes, subject to the same launch checks, including GitHub execution/context approval | +| Start continuous processing | Instructions for the user to start it in a terminal or web console; the skill does not launch it | Same boundary | +| Inspect, drain, or interrupt a registered worker | Yes, for verified local CLI or web-hosted runs | Yes, for verified local CLI or web-hosted runs | + +The web **Board** and general item editor exist only for Local Markdown. With GitHub, manage +planning in Issues and Project views; web **Operations** remains available for worker and item +processing state on both backends. An unsupported Board action does not mean the GitHub backend +cannot process or continue work. Inspect the item's available actions and use the supported +[GitHub workflow](../workflows.md#approve-github-context-and-invalidate-edits) or +[targeted continuation](worker.md#the-two-path-resume-model). Generic status moves are not +substitutes for Queue, Send back, or Resume semantics. + +## Example requests + +These examples use Codex's `$wrighty` invocation. Use the equivalent form for your +[agent surface](#supported-skill-surfaces), and replace IDs with those returned for your tracker. + +```text +$wrighty Show active work grouped by status, with counts and canonical item IDs. +$wrighty What needs attention? Separate blocked items from scheduled retries. +$wrighty Can an existing worker pick up this item? Explain the evidence; do not start one. + +# Local Markdown workflow actions +$wrighty Queue local:12 for automatic processing. Do not start a worker. +$wrighty Send local:19 back to the backlog. +$wrighty Resume the recorded session for local:23 by queueing it for a worker. +$wrighty Preview queueing the Todo items in area=api. Show exactly what would change first. + +# Worker operations on either backend +$wrighty Process this exact item with the configured worker agent and a 30-minute item timeout. +I authorize unattended processing of this item only. Keep the run attached and report the outcome. +$wrighty Process at most three eligible items with a 30-minute item timeout and a five-minute +idle timeout. Keep the run attached and report the results. +$wrighty Show me how to start a continuous worker in my terminal. +$wrighty Stop worker after its current item; let that item finish. +$wrighty Interrupt worker now, including its active agent. Report any recovery needed. +``` + +The skill uses the configured workflow statuses and reports filters or incomplete counts. +Queueing, resuming a recorded session for a worker, and starting a worker are separate effects. +Requests that authorize an effect can proceed without repeated confirmation; a preview alone +does not authorize execution. Batch results identify applied, skipped, failed, or uncertain items. +With the worker-queue policy enabled, Queue authorizes automatic processing and Send back revokes +that authorization. If the policy is disabled, execution permission remains a separate setting. +See [workflow actions](actions.md) for eligibility and revalidation. + +Worker pickup is advisory: “could pick up” is not a reservation or a timing guarantee, and +“unknown” is not permission to launch a duplicate. Worker inspection covers registrations in the +current local configuration; remote, unregistered, and other-configuration workers can be outside +that view. See [worker discovery and control](workers.md). + +## Worker ownership and stopping + +The skill launches only finite runs attached to their invoking command. It defaults to +`worker --item ID` for an exact item or `worker --once` for the next eligible item. An explicitly +requested bounded queue run may use `--max-items N`, with item and idle timeouts. That limits the +number processed, not total elapsed time or the identities of the selected items: the worker +selects eligible work as it proceeds. It is different from a frozen batch of workflow actions. + +**Start continuous workers yourself**, either in your terminal or with **Start worker** in the +web console. The skill supplies instructions and states that it has not started the process; +it does not launch a continuous worker even if the agent host offers a retained terminal. An +idle timeout alone does not change this rule. It also does not repeat finite runs to simulate +continuous processing. The skill can inspect, assess pickup from, drain, and interrupt workers +you have already started. + +For allowed finite runs, if the agent surface cannot keep the command attached through +completion, the skill supplies the command for you to run instead. This is a skill guidance +boundary; the CLI continues to support continuous workers for terminals and the web host. + +A conversation does not guarantee background execution or monitoring after task cancellation, +application exit, logout, or restart. There is no Wrighty detach command, service installation, or +startup/restart management in this workflow. Worker-spawned implementation sessions cannot +recursively start workers. + +**Drain** closes intake and lets the current item finish. **Interrupt** cancels the current agent +process tree and performs interruption bookkeeping; it does not mark the item successfully +completed. Both address a verified run ID, including individual web-hosted runs that share a +process. The skill distinguishes an accepted stop request from completed shutdown, checks the +item outcome, and does not fall back to killing an OS process. See [worker control](workers.md#cooperative-control). + +## Install and maintain the skill + +Run your agent in the configured project with access to the `wrighty` executable. For GitHub, +the agent's command environment also needs network access and an authenticated `gh` CLI with +the repository/Project permissions described in [configuration](configuration.md#initialize-the-github-backend). +Installing a skill does not grant those permissions. If tracker access fails, the agent should +report which observations are unavailable rather than invent counts or eligibility. + +Install for a selected agent, or all supported destinations: ```shell wrighty skill install --agent codex @@ -180,19 +289,8 @@ incomplete, but the skill does not present them as ready or enable automatic pro same assessment passes. Fresh worker sessions independently assess the approved context they receive; the skill does not stamp items with a reusable “verified” marker. -The bundled skill supports board overview using configured workflow order, operational triage, -shared action discovery, and scoped worker/pickup assessment. `list --json` keeps its `result` array -and adds `listing` metadata: status order, archive/filter/limit scope, returned count, and whether -the result may be truncated. See [worker discovery](workers.md). Update an installed skill through -the existing `wrighty skill update` command to receive these workflows. - -The bundled skill also executes individual Local Markdown Queue, Send back, and Resume requests -through `actions --exec --yes --expected-version --json`, after the -requested effect is authorized. CLI and web share eligibility and locked revalidation. Execution -returns the resulting state and refreshed worker pickup evidence; it does not launch a worker. -See [action execution](actions.md). - -The skill also supports reviewed Local Markdown batches through `batch preview`, `batch show`, -and `batch execute --yes`. It reports the exact frozen subset and partial results, including -uncertain outcomes after interruption. CLI and web batch operations share the Core execution loop; -the CLI persists its own previews/results for cross-process use. See [batch workflow actions](actions.md#batch-workflow-actions). +The skill's Local Markdown workflow actions share eligibility and locked revalidation with the +web Board. CLI and web batches share the Core execution loop; the CLI persists its own previews +and results for use across invocations. Worker discovery and cooperative control also use the +shared Core services. The skill describes these outcomes in conversation; it does not maintain a +separate board or worker scheduler. diff --git a/docs/reference/operator-actions.md b/docs/reference/operator-actions.md index 7eb31d4..f1282f3 100644 --- a/docs/reference/operator-actions.md +++ b/docs/reference/operator-actions.md @@ -11,8 +11,10 @@ start an operation; **guidance** means it presents state or instructions whose a elsewhere; and **view** means read-only visibility. Follow the linked reference for prerequisites, commands, claim behavior, and edge cases. -The three surfaces are: +The surfaces are: +- **Agent skill** — a conversational alternative for supported board and worker operations, + executed through the CLI. See the backend matrix below. - **Web console** — `wrighty web`, a shared machine-local web console for both backends; Local Markdown additionally supplies its board/editor. - **GitHub** — the issue, Project fields, labels, and Wrighty's single status comment. @@ -21,6 +23,28 @@ The three surfaces are: For a live item-specific catalogue, use `wrighty actions ID` or `wrighty actions ID --all --json`. See [Action discovery](actions.md) for its read-only contract and stable refusal reasons. +## Conversational alternative + +The skill offers the following workflows through natural-language requests. The detailed tables +below compare the underlying web, GitHub, and CLI controls; they do not imply that every CLI +operation has a dedicated skill workflow. + +| Goal through the skill | Local Markdown | GitHub | +| --- | --- | --- | +| Summarize planning status and inspect tracked items | Yes; complements the web Board | Yes; complements the native GitHub Project board | +| Inspect processing state, blockers, and available actions | Yes; complements web Operations | Yes; complements web Operations | +| Queue, Send back, or Resume via Board workflow execution | Individual items and reviewed batches | These executors are unavailable; explain the limit and use the appropriate planning/continuation workflow | +| Discover workers and assess item pickup | Local configuration scope | Local configuration scope, not every host connected to GitHub | +| Launch targeted or bounded work; drain or interrupt a run | Supported with authorization and a suitable process owner | Supported with authorization and a suitable process owner | +| Start a continuous worker | The skill supplies instructions; the user starts it in a terminal or web console | Same boundary | + +See [Agent skills](agent-skills.md#example-requests) for prompts, backend limitations, and process +lifetime. The skill uses the same CLI/Core policy checks; it does not recreate web requests or +bypass a backend refusal. Its own launches default to attached single-item runs; `--max-items` +requires an explicit bounded-queue request. General GitHub planning stays in Issues/Project views, while operations +are shared across backends. Existing claim-aware CLI authoring/editing can also be used through +the skill when separately requested. + ## State and authority Before acting, distinguish policy, portable lifecycle state, local operational state, and @@ -40,8 +64,8 @@ Wrighty transition. Use the supported action linked below. | Action | Web console | GitHub | CLI | Authoritative procedure | | --- | --- | --- | --- | --- | -| Browse and filter active work | **Direct:** visual status board | **Direct:** Project views and issue search | **Direct:** human or JSON listing | [Inspect and organize work](../workflows.md#inspect-and-organize-work) | -| Inspect one item's content and metadata | **View:** rendered and raw Markdown, policy, operational status, and claim state | **View:** issue plus Project fields and labels | **Direct:** full operational detail | [Work items](work-items.md) | +| Browse and filter active work | **Direct for Local Markdown:** visual status board; Operations shows processing state for both backends | **Direct:** Project views and issue search | **Direct:** human or JSON listing | [Inspect and organize work](../workflows.md#inspect-and-organize-work) | +| Inspect one item's content and metadata | **View:** Local Markdown content/editor; processing state for both backends; GitHub context inspection is content-free | **View:** issue plus Project fields and labels | **Direct:** full operational detail | [Work items](work-items.md) | | Determine claim ownership or takeover eligibility | **View:** current ownership and available controls | **View:** claim projection/comment; exact recovery remains installation-aware | **Direct:** complete ownership inspection | [Claims and ownership](claims.md#claim-ownership-fencing-and-takeover) | | Inspect a retained session or workspace | **View:** local session address and bounded workspace state | **Guidance:** status comment identifies the recording host/branch according to privacy policy | **Direct:** session, resume, and workspace inventory | [Retained workspaces](worker.md#retained-workspaces) | | Find blocked, queued, retrying, or completed work | **View:** operational-status badges and callouts | **View:** authoritative lifecycle label plus display fields | **Direct:** grouped operational status | [Discovering what needs attention](worker.md#discovering-what-needs-attention-wrighty-status) | @@ -51,10 +75,10 @@ Wrighty transition. Use the supported action linked below. | Action | Web console | GitHub | CLI | Authoritative procedure | | --- | --- | --- | --- | --- | | Create a work item | **Direct:** structured Local Markdown form | **Direct:** configured Project/issue form paths | **Direct:** retry-safe creation on either backend | [Collaboratively author a substantial work item](../workflows.md#collaboratively-author-a-substantial-work-item) | -| Change title, instructions, status, or priority | **Direct:** requires a suitable editing claim | **Direct:** native issue/Project editing exists; Wrighty claim coordination still applies | **Direct:** claim-aware editing and moving | [Moving and editing](work-items.md#moving-and-editing) | -| Allow or prevent automatic execution | **Direct:** execution-policy editor control | **Policy:** edit the authoritative Wrighty policy - execution field | **Direct:** create/edit policy options | [Create and dispatch one unattended item](../workflows.md#create-and-dispatch-one-unattended-item) | -| Choose the agent policy | **Direct:** agent-policy editor control when the item is not locked to a retained retry | **Policy:** edit the authoritative Wrighty policy - agent field | **Direct:** create/edit policy options or worker-level override | [GitHub worker policy](configuration.md#initialize-the-github-backend) | -| Inspect or approve execution context | Not applicable: Local content is approved by definition | **Direct:** native Project field or web repository control plane | **Direct:** `context` and `approve` | [Approve GitHub context and invalidate edits](../workflows.md#approve-github-context-and-invalidate-edits) | +| Change title, instructions, status, or priority | **Direct for Local Markdown:** requires a suitable editing claim | **Direct:** native issue/Project editing exists; Wrighty claim coordination still applies | **Direct:** claim-aware editing and moving | [Moving and editing](work-items.md#moving-and-editing) | +| Allow or prevent automatic execution | **Direct for Local Markdown:** execution-policy editor control | **Policy:** edit the authoritative Wrighty policy - execution field | **Direct:** create/edit policy options | [Create and dispatch one unattended item](../workflows.md#create-and-dispatch-one-unattended-item) | +| Choose the agent policy | **Direct for Local Markdown:** agent-policy editor control when the item is not locked to a retained retry | **Policy:** edit the authoritative Wrighty policy - agent field | **Direct:** create/edit policy options or worker-level override | [GitHub worker policy](configuration.md#initialize-the-github-backend) | +| Inspect or approve execution context | **Direct for GitHub:** protected inspect/approve controls; Local content is approved by definition | **Direct:** native Project field | **Direct:** `context` and `approve` | [Approve GitHub context and invalidate edits](../workflows.md#approve-github-context-and-invalidate-edits) | | Initialize or validate backend resources | **View:** explicit read-only GitHub target validation; no migration | **View:** resources created by initialization | **Direct:** discovery, initialization, and validation | [Configuration](configuration.md) | Changing policy does not itself launch a worker. A retained vendor-native retry also remains bound @@ -69,7 +93,7 @@ to its recorded agent; see [usage exhaustion and deferred retry](worker.md#usage | Release a claim | **Direct:** own-claim and guarded override controls | No native fenced Wrighty action | **Direct** | [Recovery paths](claims.md#recovery-paths) | | Clarify a paused item and preserve its recorded session | **Direct:** edit with explicit queue, hand-back, release, or retain choices | **Direct:** issue content can be clarified; use Wrighty for the claim/session transition | **Direct:** atomic edit/takeover and continuation paths | [Clarify and resume the same session](../workflows.md#clarify-an-item-and-resume-the-same-agent-session) | | Queue a paused recorded session for a continuous worker | **Direct** | **Guidance:** status comment supplies the Wrighty path | **Direct** | [Clarify and resume the same session](../workflows.md#clarify-an-item-and-resume-the-same-agent-session) | -| Queue, send back, or resume multiple eligible Board cards | **Direct for Local Markdown:** confirmed column actions process the frozen filtered set sequentially, up to 100 at a time | Not available | Repeat the corresponding single-item action | [Web console](web-console.md) | +| Queue, send back, or resume multiple eligible Board cards | **Direct for Local Markdown:** confirmed column actions process the frozen filtered set sequentially, up to 100 at a time | Not available | **Direct for Local Markdown:** `batch preview`, `show`, and `execute` on a reviewed frozen selection | [Batch workflow actions](actions.md#batch-workflow-actions) | | Hand a claim back for interactive continuation | **Direct:** produces the fenced resume command and can open its CLI on macOS or native Windows | **Guidance:** status comment supplies the recording-installation path | **Direct:** produces or executes the resume command | [The two-path resume model](worker.md#the-two-path-resume-model) | ## Run and resume agents @@ -118,8 +142,8 @@ Not every surface is meant to reach parity: Markdown-only, while validated launch of needs-attention and unclaimed Done sessions from Operations is shared. Its narrow GitHub context approve/reapprove action also lives in the repository control plane; - neither capability duplicates general GitHub issue/Project editing. Operations may host one - headless continuous worker for the lifetime of the web process. See + neither capability duplicates general GitHub issue/Project editing. Operations may host multiple + headless continuous workers for the lifetime of the web process. See [Web console](web-console.md). - GitHub provides policy, portable state, and human guidance. Exact session, retry, provider, and workspace operations execute through Wrighty on the recording installation. See diff --git a/docs/reference/web-console.md b/docs/reference/web-console.md index 5a4e5d4..20c6379 100644 --- a/docs/reference/web-console.md +++ b/docs/reference/web-console.md @@ -45,6 +45,14 @@ GitHub never renders or authorizes those Local-only item mutation routes. The Local Markdown Operations tab complements the board with process and recovery state; it does not replace the board. +Prefer to operate from an agent conversation? The [Wrighty skill](agent-skills.md) is an alternative +for status summaries, processing-state inspection, and worker launch/control on both backends, +plus individual and batch Board workflow actions on Local Markdown. GitHub planning remains in +Issues and Project views. The skill's worker lifetime depends on its owning command or terminal; +web-hosted workers remain owned by this web process. The skill launches only attached finite runs. +For continuous processing it directs you to your terminal or **Start worker** here, then can +inspect or stop the existing worker. + ## Start, observe, and stop workers The header's **Workers** button opens an installation-local anchored popover, matching the diff --git a/docs/workflows.md b/docs/workflows.md index fc3721a..d85cb30 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -1,10 +1,11 @@ # Wrighty workflows Wrighty supports interactive agent work, unattended worker processing, and human intervention -without making those separate systems. The CLI and web console read and mutate the -same items, claims, dispatch state, and recorded agent-session addresses. +without making those separate systems. The agent skill operates through the CLI; the skill, CLI, +and web console read and mutate the same items, claims, dispatch state, and recorded agent-session +addresses. Use the skill as a conversational alternative to the web console for supported operations. -You can switch between the CLI and web console while working on the same item. No export, import, or +You can switch between the skill, CLI, and web console while working on the same item. No export, import, or synchronization step is required. Claim fencing still applies: changing surfaces does not silently grant the new surface ownership. Use the takeover, save, release, queue, and hand-back actions described below. @@ -19,7 +20,7 @@ described below. > operating systems. It keeps the copyable command fallback everywhere. Where no web-only route > exists, the guide says so explicitly. -For a task-by-task capability matrix covering the web console, GitHub, and CLI, use +For a task-by-task capability matrix covering the skill, web console, GitHub, and CLI, use [Operator actions by surface](reference/operator-actions.md). That comparison links back to the authoritative procedures in this guide and the reference pages rather than repeating them. @@ -27,15 +28,46 @@ authoritative procedures in this guide and the reference pages rather than repea | Goal | Start with | Switch to the other surface when | | --- | --- | --- | -| Inspect and organize the backlog | `wrighty list`, `wrighty get`, or `wrighty web` | You want compact/JSON output, or a visual board and Markdown preview | +| Inspect and organize the backlog | Ask the skill for a status overview, use `wrighty list`/`get`, or open the Local Markdown Board / GitHub Project | You want conversational follow-up, compact/JSON output, or visual planning | +| Queue, send back, or resume eligible Local Markdown items | Ask the skill for an individual action or reviewed batch, or use the web Board | You prefer a conversation or visual selection; these Board executors do not support GitHub | +| Inspect processing state and workers on either backend | Ask the skill what needs attention and which workers are running, or open web Operations | You want conversational triage or a visual operations view | | Collaboratively define a feature | Claude, Codex, Copilot, or OpenCode with the Wrighty skill | The item exists and you want visual editing or backlog placement | -| Give one item to an unattended agent | `wrighty worker --once` | You want to monitor state, edit requirements, take over, or archive | -| Process eligible work continuously | `wrighty worker` or **Start worker** in the web console | An item needs human attention or backlog eligibility needs editing | +| Give one exact item to an unattended agent | Ask the skill to process that item, or use `wrighty worker --item ID`; `--once` instead chooses the next eligible item | You want to monitor state, edit requirements, take over, or archive | +| Process eligible work continuously | Start `wrighty worker` yourself in a terminal, or use **Start worker** in the web console; the skill supplies instructions and can inspect/control existing runs | An item needs human attention or backlog eligibility needs editing | +| Stop a worker on either backend | Ask the skill to drain or interrupt its run ID, or use the web worker controls | You want a conversational explanation or visual monitoring of the stop outcome | | Let an interactive agent choose work | Start Claude, Codex, Copilot, or OpenCode with the Wrighty skill | You want to inspect or take over the claimed item | | Clarify a paused agent item | `wrighty edit ID --takeover` or **Take over for editing** | You prefer terminal editing or the web console form | ## Inspect and organize work +### Agent skill + +Ask for either planning status or processing state: + +```text +$wrighty Show active items grouped by workflow status, including counts and IDs. +$wrighty What is blocked, what is scheduled to retry, and which workers are running? +``` + +Both requests work with either backend. A GitHub overview reads the configured Project's statuses +and tracked issues; it does not create a second planning board. GitHub Issues and Project views +remain the place for visual GitHub planning. Web Operations and the skill provide processing-state +inspection for both backends. + +For Local Markdown, the skill can also Queue, Send back, or Resume eligible items individually or +in reviewed batches. For example, ask it to preview queueing selected IDs, inspect the proposed +effects, then authorize that selection. These workflow executors do not support GitHub. The skill +should explain that limit and the supported next step, without changing Project fields or +recreating a batch through a loop of different mutations. Supported GitHub CLI creation and +claim-aware editing remain available as separate workflows. See +[skill capabilities and examples](reference/agent-skills.md#capabilities-by-backend). + +Worker inspection, pickup assessment, targeted or explicitly requested bounded launch, drain, +and interrupt support both backends. Skill-launched runs stay attached and default to one item; +you start continuous workers yourself in a terminal or web console. Worker visibility/control is +local to the selected configuration, even for GitHub. Queueing never starts a worker by itself. +See [worker ownership and stopping](reference/agent-skills.md#worker-ownership-and-stopping). + ### CLI List active work and inspect one item: @@ -73,8 +105,9 @@ with content-free diagnostics and the protected approve/reapprove action. ### Switching surfaces -Read-only inspection never changes ownership. You can alternate freely between `list`/`get` and -the web console. A web console refresh and the next CLI command both read the authoritative store. +Read-only inspection never changes ownership. You can alternate freely between skill requests, +`list`/`get`, and the web console. A web console refresh and the next skill/CLI query read the +authoritative store. ## Collaboratively author a substantial work item diff --git a/skills/wrighty/SKILL.md b/skills/wrighty/SKILL.md index 7968527..b5fa3f4 100644 --- a/skills/wrighty/SKILL.md +++ b/skills/wrighty/SKILL.md @@ -5,7 +5,7 @@ description: Safely operate Wrighty through the `wrighty` CLI. Use only when the # Wrighty - + Operate Wrighty state only through the `wrighty` command. Never mutate tracked state by editing local Markdown, invoking `gh`, calling GitHub APIs/MCP, writing claim comments, or changing Project @@ -15,7 +15,10 @@ For board overview, triage, individual and batch Queue/Send back/Resume actions, [references/board-and-workers.md](references/board-and-workers.md). Use `list --json` for workflow columns, `actions --json` for the shared action catalogue, and `workers [--item ] --json` for scoped worker evidence. Discovery does not authorize mutations or worker launches. -For authorized foreground/terminal worker launch, exact-run inspection, drain, or interrupt, read +Launch only attached finite worker runs: default to `--item ` or `--once`; use `--max-items N` +only for an explicitly requested bounded queue run. Continuous workers must be started by the +user in their terminal or through the web console; provide instructions, do not start one yourself. +For authorized bounded worker launch, exact-run inspection, drain, or interrupt, read [references/worker-control.md](references/worker-control.md). ## Workflow diff --git a/skills/wrighty/references/board-and-workers.md b/skills/wrighty/references/board-and-workers.md index d705c63..f586c32 100644 --- a/skills/wrighty/references/board-and-workers.md +++ b/skills/wrighty/references/board-and-workers.md @@ -4,6 +4,9 @@ Use these workflows when the user asks to see their Wrighty board, triage blocke workers, or assess whether a worker could pick up a named item. These are observations, not permission to change items or launch processes. +Present results in readable Markdown. Use a table for multiple items or status counts, and a +concise summary for one item. Avoid raw JSON unless requested. + ## Board by workflow status Run `wrighty list --json`. Its existing `result` array contains canonical IDs, workflow status, @@ -133,8 +136,10 @@ is not evidence of open intake. Capability fields do not waive fresh identity ch Assessment describes the item's current state, not its state after a proposed Queue/Resume action. After an authorized mutation, re-read the item and assessment before describing pickup prospects. Queueing and launching are separate permissions. With no suitable observed worker, explain the -reason and offer an appropriate bounded or continuous launch only if the user's intent calls for -it. A next-item `worker --once` does not target a named item; `worker --item ` does. +reason and offer an attached `--item` or `--once` run only if the user's intent calls for it; +`--max-items N` requires an explicitly requested bounded queue run. For continuous processing, +provide instructions for the user to start it in their terminal or web console; do not launch it +yourself. A next-item `worker --once` does not target a named item; `worker --item ` does. Waiting must be bounded or explicitly hosted by the agent platform. Recheck only when asked to wait or when confirming an authorized operation, and stop on meaningful progress, failure, or a diff --git a/skills/wrighty/references/worker-control.md b/skills/wrighty/references/worker-control.md index e585d77..29ee62b 100644 --- a/skills/wrighty/references/worker-control.md +++ b/skills/wrighty/references/worker-control.md @@ -18,7 +18,9 @@ Choose a worker agent from explicit user intent, item policy, or configured defa hosting this conversation is not a default. Preserve configured workspace and profile choices unless the user requests an override. Never probe a paid vendor merely to check readiness. -Use the smallest processing scope that meets the request: +Default to one attached run: `--item ` for a named item or `--once` for the next eligible item. +Use `--max-items N` only when the user explicitly requests processing a bounded number of eligible +items. Include item and idle timeouts appropriate to that request and keep the run attached: ```shell wrighty worker --item --item-timeout 30m --yes --json @@ -30,30 +32,36 @@ wrighty worker --max-items 3 --idle-timeout 5m --item-timeout 30m --yes --json eligible item. Do not replace one with the other. Use `--agent`, `--profile`, `--filter name=value`, `--workspace-mode`, `--from`, and `--to` only within the requested scope. `--item-timeout` bounds each item, not the whole worker. `--max-items` bounds item count, and `--idle-timeout` bounds an idle -period. A targeted run already has an effective item limit of one. Do not take over claims or force +period. The count limit is not a total wall-clock deadline or a frozen selection of named items; +the worker selects eligible work as it proceeds. Do not translate a request for specific IDs into +`--max-items N`. A targeted run already has an effective item limit of one. Do not take over claims or force `--fresh`, `--resume`, or `--handoff` merely to get past a refusal. ## Own the process honestly -For Codex, Claude, Copilot, and OpenCode surfaces, foreground execution is the portable path. -Keep a bounded run attached to the invoking command, consuming its output through completion. -For authorized continuous work, use a user-owned terminal or a host-provided retained terminal -whose lifetime is established. For example, in that terminal: +For Codex, Claude, Copilot, and OpenCode surfaces, keep every skill-launched run attached to its +invoking command and consume its output through completion. Do not start a continuous worker, +even when the user requests one or the host offers a retained terminal. An idle or item timeout +alone does not make a continuous worker an allowed finite run. Do not emulate continuous work by +repeatedly launching `--once` or `--max-items` runs or by scheduling a keepalive/relaunch loop. + +For continuous processing, give the user the foreground command to run in their own terminal, or +direct them to **Start worker** in the web console. Explain that you have not started it. For example: ```shell wrighty worker --idle-timeout 30m --item-timeout 30m --yes --json ``` -State the terminal/process owner and its actual cancellation and exit behavior before launching. -A retained terminal keeps the executable running without a model reasoning loop, but is not a -promise of survival across task cancellation, app exit, logout, or restart. There is no Wrighty -detach command. Do not emulate one with background shell syntax or invent a keepalive loop. -If the available tool cannot retain the process for the required duration, provide the exact -foreground command for the user's terminal and say it has not been started. +For an allowed finite launch, state the invoking command/process owner and its actual cancellation +and exit behavior. If the available tool cannot keep the run attached through completion, provide +the command for the user's terminal instead. Do not promise survival across task cancellation, +app exit, logout, or restart. There is no Wrighty detach command; do not emulate one with background +shell syntax, a detached session, or a terminal-opening tool. -Existing web-hosted runs can also provide continuous processing. Their launch remains in the web -console; starting `wrighty web` alone does not start a worker. Do not spoof its browser requests. -No vendor-specific detached launch path is offered by this skill. +The skill may inspect, assess pickup from, drain, or interrupt existing continuous workers within +the user's authorization. Web-hosted launches remain a user action in the web console; do not +launch one through browser automation or spoofed requests. Starting `wrighty web` alone does not +start a worker. No vendor-specific detached launch path is offered by this skill. Worker-spawned sessions must not start workers recursively. `WRIGHTY_WORKER_CHILD=1` marks that context and live launch returns `WORKER_RECURSIVE_LAUNCH`; do not remove the marker to bypass it.