shakacode / shakacode/agent-workflows
Use typed issue/PR task titles and rename tasks when a PR opens
Nobody has claimed this yet.
- Dominant language
- Ruby
- Stars
- 7
- Forks
- 1
- Avg merge
- 1d 16h
- Merged PRs (30d)
- 150
Description
Why
Task titles should make the repository, source issue, current PR, and purpose easy to identify. Bare references such as AW #225, #836 do not distinguish an issue from a PR. The current batch-title format puts a timestamp before the description and omits PR identifiers, including for PR-only work.
An issue normally starts before a PR exists. The naming convention must support that lifecycle instead of requiring a PR number at task creation.
Proposed convention
Use this visible task-title format:
<PREFIX> [i<ISSUE>] [pr<PR>] -- <DESCRIPTION>
Brackets denote optional fields and are not rendered. Use one space between fields and the literal ASCII separator --.
| Situation | Title |
|---|---|
| Issue work before a PR exists | AW i225 -- exact review-check names |
| Same task after opening or adopting its PR | AW i225 pr836 -- exact review-check names |
| PR work without a verified source issue | AW pr836 -- exact review-check names |
| Investigation without an issue or PR | AW -- investigate review-check names |
| Linear source issue | AW ENG-225 pr836 -- exact review-check names |
| Batch with multiple unrelated targets | AW -- review workflow cleanup batch |
Resolve the prefix through the existing repo_prefix seam and existing deterministic fallback; do not introduce another prefix configuration. Consumer repositories should choose distinct prefixes where abbreviations collide. Preserve native Linear identifiers rather than translating them into GitHub-style i numbers.
Remove mandatory timestamps and response-local A/B/C letters from visible task titles. Keep launch timestamps and batch distinctions in existing coordination metadata. Use short, distinctive descriptions with meaningful words first to reduce sidebar truncation. Do not add model, priority, or changing status fields to this title format.
Rename lifecycle
- At task creation or adoption, render only identifiers already verified for the owned work. Unknown fields are omitted, never fabricated or shown as placeholders.
- After a PR is successfully created or an existing PR is adopted, verify its repository, number, and association with the task's owned work. Rename the same task to add
prN, preserving the source issue and description. - On resume or reconciliation, repair an outdated managed title from verified current ownership records. This covers a PR created just before interruption or a failed earlier rename.
- If a PR is explicitly superseded, show the verified replacement PR; preserve previous PR references in existing task/coordination history.
- Keep issue and PR references at completion for later retrieval. Do not repeatedly rename for CI, review, merge, or archive status changes.
- Explicit user title overrides take precedence. Do not continuously overwrite a user-chosen title. The implementation should use existing task records and explicit instructions rather than add a new tracking subsystem.
Codex desktop currently exposes mcp__codex_app__set_thread_title, accepting title and an optional threadId (omitting it targets the calling task). This provides an in-place rename capability; a replacement task is unnecessary. Shared workflow instructions should express the portable behavior through the host's available title capability rather than require this particular tool on every host.
When the host supports readback, confirm the resulting visible title. If renaming is unavailable or fails, retain the task, record the intended title in its existing handoff, and report the limitation without claiming success or blocking otherwise authorized development. Retry at a normal resume/reconciliation point, not through a new polling automation.
Identity, scope, and edge cases
- Titles are display metadata. Stable task IDs, repository-qualified target identities, claims, thread handles, branches, and routing remain authoritative and unchanged by a rename.
- Only verified owned targets supply identifiers. Numbers mentioned in comments, examples, dependencies, or review findings are not eligible merely because they appear in context. Preserve existing trust and source-issue verification requirements.
- For batches, include an issue only when there is one verified source issue or an explicitly verified umbrella source issue. Include a PR only when there is one unambiguous owned PR. Omit a field with multiple eligible values; list full membership in existing batch records. Never guess a primary issue or PR.
- Multiple tasks for the same issue/PR should use distinct purposes in their descriptions, such as implementation, review, or verification. A shared title prefix does not authorize duplicate implementation ownership.
- Do not imply that identifiers from different repositories belong to the prefix repository. Cross-repository coordination should use a descriptive coordinator title and repository-qualified member records.
- Apply this to visible agent task titles and generated task-title prompts. Do not add the PR's own number to GitHub PR titles or rename branches to mirror a changing display title.
- Normalize newly created/adopted tasks and tasks resumed through the updated workflow. Bulk renaming unrelated or archived tasks is outside scope.
Current behavior and implementation surfaces
The canonical rules in workflows/pr-batch-intake.md, under Verified Batch Title Selection, currently specify <PROJECT> <A?> <ID?> <MM-DD HH:MM> - <title>. They permit one verified source issue but exclude PRs as title identifiers. This proposal extends the earlier issue-title work in #437.
skills/plan-pr-batch/references/handoff.md already requires applying the resolved title at creation or using a host rename capability. Extend that existing behavior through PR creation/adoption and resume; keep a single canonical naming definition.
Update dependent prompt templates and continuation prompts, planning/execution handoff references, host capability guidance where needed, and user-facing documentation. Inspect existing prompt contract checks, including skills/plan-pr-batch/scripts/check_goal_prompt_size.rb, for the old title format. Audit title-derived batch-short/thread-handle construction so removing visible timestamps or letters does not change stable identities or remove required disambiguation.
Acceptance criteria
- Canonical documentation defines the syntax, optional fields, identifier verification, exceptions, and lifecycle above.
- Issue-only work starts with
iNand acquiresprNon the same task after verified PR creation/adoption. - PR-only work includes
prN; no-identifier work has clean spacing and no placeholders. - Resume repairs a stale managed title; repeating reconciliation leaves an already-correct title unchanged.
- Replaced PRs, multiple targets, native Linear IDs, explicit user overrides, and unsupported/failed rename behavior are covered.
- Renames preserve stable task identity, ownership, routing, branches, and existing coordination handles.
- Creation and continuation templates agree with the canonical rules; ordinary visible titles no longer require timestamps or batch letters.
- Validation uses behavior/examples and structural contracts where appropriate, without introducing tests that pin long exact prose passages.
- Run
bin/validate; meaningful dirty skill changes require a post-commit rerun for full coverage under existing repository policy.
Changelog: deferred_to_update_changelog.
This issue specifies the change; implementation and bulk task renaming are not part of filing it.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Verified Batch Title Selection section in workflows/pr-batch-intake.md and the existing title behavior in skills/plan-pr-batch/references/handoff.md. Inspect dependent prompt templates, continuation prompts, title-derived batch or thread-handle construction, and the contract check in skills/plan-pr-batch/scripts/check_goal_prompt_size.rb. Done means the documented lifecycle, identifier cases, rename behavior, stable identities, and prompt contracts agree, with bin/validate passing.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- ruby
- Domain
- developer-experience, documentation, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 64/100