agent-workstream-planning

name	agent-workstream-planning
description	Triage open issues as a portfolio, identify active work and dependencies, prioritize safe parallel streams, and prepare implementation handoffs.
compatibility	opencode
metadata	{"audience":"maintainers","repo":"perkcord"}

Agent Workstream Planning Skill

Purpose: help an agent act like a lightweight engineering lead across the issue queue, not just within a single ticket.

When To Use

• The user wants to know what should be worked on next.
• The user wants a prioritized list of open issues.
• The user wants to avoid collisions with work already in flight.
• The user wants upstream/downstream dependencies mapped before implementation.
• The user wants kickoff prompts for follow-on implementation agents.

Relationship To Other Skills

• Use this skill for the portfolio-level question: what should move next, what is blocked, and what is safe to run in parallel?
• After a path is selected, hand off to .opencode/skills/issue-delivery-kickoff/SKILL.md for the single-issue kickoff prompt.

Core Workflow

1. Inventory the issue set.
2. Detect active work already in progress.
3. Check whether candidate issues are already fully or partially done.
4. Identify issue dependencies and natural sequencing.
5. Identify conflict-prone parallel work.
6. Prioritize candidate workstreams.
7. Collaborate with the user on direction.
8. Prepare a fresh-worktree implementation handoff or continuation note.

Inputs To Gather

• AGENTS.md (and AGENTS.local.md when present) for repo invariants and product decisions
• Open GitHub issues
• Open pull requests
• Recent issue comments, especially owner comments
• Local repo evidence showing work may already be done

Active-Work Detection

Treat an issue as already in flight when one or more of these are true:

• there is an open PR that clearly matches the issue scope
• a recent owner comment says work has started or a follow-up pass is underway
• the repo already contains most or all of the requested behavior and the likely next step is verification/closure

Do not recommend an issue as a clean new stream until you check those signals.

Completion-State Detection

For each candidate issue, explicitly classify it as one of:

• already done - likely closeable after verification
• partially done - narrow the remaining scope before kickoff
• not started - suitable for a fresh implementation lane

When an issue is partially done, prefer recommending:

• a narrowed remaining slice
• a follow-up issue split
• or a verification-and-close path

rather than treating the original issue body as fully current.

Dependency Mapping

For each candidate issue, classify related work as:

• hard blocker - cannot proceed safely until this exists
• implied prerequisite - not tracked as a separate blocker, but should be designed first
• natural follow-on - logically comes next after the issue lands
• adjacent - touches similar areas but need not be sequenced

Look for dependencies in:

• issue bodies and comments
• schema/data model assumptions
• shared backend primitives
• auth/session/provider coupling
• docs that still describe an older product policy

Conflict Check

Assume workstreams conflict when they touch the same:

• session or identity model
• auth/authz boundaries
• provider/billing primitives
• shared admin forms or settings contracts
• Convex function surfaces

Parallel work is safer when it is isolated to:

• distinct UI surfaces
• unrelated infra/runbook documentation
• narrow admin ergonomics
• self-contained visual polish

Also check for multi-target deployment blindness:

• shared SaaS vs white-label/client deployment assumptions
• Terraform state/backend ownership confusion
• automation that might target the wrong Vercel/Convex/project lane

Prioritization Heuristics

Bias toward work that is:

• high risk reduction (security, auth, billing correctness)
• high leverage for later work (foundations, topology clarity, observability)
• highly visible but low conflict (good demo value)
• small and verifiable

De-prioritize work that is:

• already being handled elsewhere
• likely already complete
• broad and under-specified without policy decisions

User Collaboration Pattern

After triage, help the user choose a path by presenting a short set of options such as:

• most urgent
• most splashy
• safest quick win
• most strategic

Then refine based on user direction before preparing a handoff.

Active Agent Coordination

If an agent is already working a related stream:

• avoid creating a duplicate kickoff for the same scope
• prepare a continuation note instead when the user wants to inform the running agent of likely next steps
• keep continuation notes additive, not disruptive: do not redirect the active agent away from its current issue unless the user explicitly wants that

Handoff Rule

Any implementation agent should start from a fresh worktree + branch, not the main worktree.

Suggested pattern:

git worktree add "../perkcord-issue-<number>" -b "feat/issue-<number>-<slug>" main

Every kickoff prompt should explicitly say:

• check whether the issue is already done first
• narrow the issue if it is only partially done
• stop and report evidence if the issue should likely be closed
• only code after that verification step

For deployment/infra issues, kickoff prompts should also explicitly say:

• verify the correct target topology first
• account for white-label/client lanes separately from shared/internal lanes when relevant

Recommended Output Shape

• prioritized issues or workstreams
• issues excluded due to active work
• issues likely already done or needing verification/closure
• dependency chain around the selected issue
• conflict-prone parallel work list
• 2-3 path options when the user is still deciding
• final kickoff prompt for the chosen stream or continuation prompt for an already-running agent

Future-Friendly Note

This workflow is a good fit for a future dedicated agent-kickoff/orchestration tool. Until that exists, produce prompts that are structured enough to hand directly to a new agent.

Verification

• Ensure the selected issue was checked for already-done status.
• Ensure active work detection included both open PRs and recent issue comments.
• Ensure the final handoff mentions a fresh worktree.
• If you change shared kickoff guardrails, update .opencode/skills/issue-delivery-kickoff/SKILL.md in the same pass.
• If this workflow improves, add a note to docs/agentic/agentic-improvement-log.md.