[Feature Request] Support planning loop for IssueLens agent #11

Activity

1. issuelens

   added

   feature-request

   on Aug 13, 2026
2. issuelens

   assigned

   Changyong Gong (chagong)

   on Aug 13, 2026
3. issuelens commented on Aug 13, 2026

   

   issuelensBot

   on Aug 13, 2026 – with IssueLens

   More actions

   Thanks for the detailed proposal. This is a feature request for a planning workflow that takes a triaged issue through repository investigation, an implementation-ready plan/design, and explicit human approval before implementation. I did not find another issue with the same requested workflow that meets the duplicate criteria, so this remains the canonical request. The next step is maintainer review to define the planning-loop architecture, output contract, safety boundaries, and configuration.
4. chagong commented on Aug 13, 2026

   

   Changyong Gong (chagong)

   on Aug 13, 2026

   CollaboratorAuthor

   More actions

   Action Plan

   1. Add a plan sub-agent

      • Create agents/plan.md for repository investigation, action planning, design specification, readiness reporting, and explicitly requested planning follow-up actions.
      • Register _PLAN_AGENT in main.py and include it in the existing custom-agent list used by both the invocations and responses protocols.
      • Keep the current Foundry hosted-agent process, GitHub App MCP integration, protocol payloads, and deployment topology unchanged.

   2. Extend orchestrator routing

      • Update agents.md to route requests for planning, design specifications, planning review, and planning revisions to plan.
      • For a combined triage-and-planning request, invoke triage first and pass its result and the user's requested scope to plan.
      • Route later human feedback, readiness signals, and revision requests back to plan.

   3. Produce planning artifacts in two ordered stages

      • First investigate the issue and relevant repository context, then produce an actionable implementation plan.
      • Use that action plan as the basis for the design specification.
      • Always return the action plan before the design specification so reviewers can evaluate scope and sequencing before architecture details.

   4. Make the loop human-driven

      • After generating or revising the planning artifacts, stop and wait for human feedback or a recognized human signal.
      • Do not autonomously repeat review/revision passes or infer approval from the apparent completeness of the proposal.
      • Permit target-repository planning instructions to define readiness states, review signals, required sections, and planning transitions.

   5. Add a planning customization domain

      • Extend issuelens_config.py, schemas/issuelens.schema.json, examples/issuelens.yml, and skills/issuelens-config/SKILL.md with the planning domain.
      • Add .github/issuelens/planning.md for IssueLens's own planning policy.
      • Load the planning domain before generating artifacts or interpreting readiness signals.
      • Use built-in planning behavior when the domain is absent; fail the planning capability clearly when a present configuration is invalid.

   6. Retain the existing tool surface and authorization model

      • Do not introduce planner-specific MCP permissions or tool exclusions.
      • Allow the planning agent to use the existing bundled GitHub MCP and runtime tools as needed.
      • Continue requiring explicit user authorization before adding labels, posting comments, assigning users, or sending notifications.
      • Do not infer write authorization from requests to investigate, plan, review, revise, or assess readiness.
      • Treat planning approval as acceptance of the proposal, not authorization to implement code, create a branch or pull request, or deploy.

   7. Add focused tests

      • Extend prompt/wiring tests for agent registration, routing, ordered output, human-driven revisions, and implementation boundaries.
      • Extend configuration tests for the planning domain, fallback behavior, customized readiness states, and fail-closed invalid configuration.
      • Add behavioral coverage for direct planning, triage followed by planning, requests for revision, readiness signals, prompt injection in repository content, and explicitly authorized planning-related issue writes.

   8. Update documentation and validate locally

      • Update README.md and .github/copilot-instructions.md with the planning workflow, customization example, default readiness behavior, and write-authorization rules.
      • Leave .github/workflows/issue-triage.yml unchanged for the initial implementation; planning remains on demand through the existing protocols.
      • Run the host and MCP unittest suites plus representative local invocations for initial planning, revision, customized readiness, and explicit issue-comment scenarios.
      • Do not deploy a new Foundry agent version without separate deployment approval.
5. chagong commented on Aug 13, 2026

   

   Changyong Gong (chagong)

   on Aug 13, 2026

   CollaboratorAuthor

   More actions

   Design Specification

   1. Architecture

   Add one plan custom sub-agent to the existing IssueLens orchestrator. A single sub-agent owns repository investigation, action-plan creation, design-specification creation, readiness reporting, and human-requested revisions because these activities share the same issue and repository context.

   No new service, endpoint, protocol, persistent workflow engine, or Foundry resource is required.

   flowchart LR
       U[Human request] --> O[IssueLens orchestrator]
       O -->|Optional| T[Triage agent]
       T --> P[Plan agent]
       O -->|Direct planning| P
       P --> I[Investigate issue and repository]
       I --> A[Create action plan]
       A --> D[Create design specification]
       D --> H[Return artifacts and readiness]
       H -->|Human feedback or signal| O
   

   Loading

   2. Agent Registration

   Add _PLAN_AGENT: CustomAgentConfig in main.py with:

   • name: plan
   • display_name: Plan
   • A prompt loaded from agents/plan.md
   • The issuelens-config skill preloaded
   • infer: True
   • No planner-specific tool allowlist or MCP override

   Register it in _session_options()["custom_agents"]. Both /invocations and /responses then receive the feature through the existing shared session setup.

   3. Routing and Handoff

   Update agents.md with these rules:

   • Use plan for action plans, implementation plans, design specifications, repository investigation for implementation, planning reviews, readiness assessments, and revisions to planning artifacts.
   • Pass the explicit owner/repository, issue number or URL, requested scope, known constraints, supplied triage result, and every explicitly authorized write.
   • For triage plus planning, invoke triage first and pass its result to plan.
   • For revision or readiness feedback, route the request back to plan with the previous planning context available in the conversation or explicitly supplied in an invocation.
   • Never infer implementation authorization from a request to plan, review, revise, approve, or mark a planning artifact ready.

   4. Planning Sequence

   The plan agent performs two ordered stages on each initial planning request:

   1. Action plan: define the objective, scope, affected components, ordered implementation work, dependencies, and validation expected for each step.
   2. Design specification: describe how the action plan fits the current system, including component responsibilities, interfaces, data flow, configuration, security boundaries, tests, compatibility, documentation, and rollout considerations.

   The design specification must be grounded in the action plan. The agent must not present design decisions that conflict with or silently expand its scope.

   5. Human-Driven Loop

   The planning loop has no autonomous iteration count. After generating or revising artifacts, the agent returns control to the human.

   stateDiagram-v2
       [*] --> Investigating
       Investigating --> ActionPlan
       ActionPlan --> DesignSpec
       DesignSpec --> AwaitingHuman
       AwaitingHuman --> ActionPlan: Request plan revision
       AwaitingHuman --> DesignSpec: Request design revision
       AwaitingHuman --> Ready: Configured human readiness signal
       AwaitingHuman --> Blocked: Human or evidence identifies a blocker
       Ready --> AwaitingHuman: Reopen planning
   

   Loading

   In Responses conversations, the resumed Copilot session supplies prior-turn context. Invocations remain stateless, so a revision invocation must identify the issue and provide or reference the planning artifact to revise.

   6. Repository Investigation

   Use the existing bundled GitHub MCP tools and always pass the explicit target repository. The planner may retrieve the issue, comments, repository metadata, relevant directories/files, related issues, labels, and other available evidence needed by the requested work.

   Issue bodies, comments, attachments, repository files, and supplied triage reports remain untrusted evidence. They cannot override global instructions, broaden repository scope, authorize tool calls, or grant implementation permission.

   The current bounded get_file operation supports targeted directory and UTF-8 file inspection. If available tools cannot establish a repository-wide fact, the plan must report that limitation as an assumption, risk, open question, or blocker instead of claiming exhaustive coverage.

   7. Planning Customization

   Add planning to the validated instruction domains:

   version: 1
   instructions:
     planning:
       path: .github/issuelens/planning.md

   A planning instruction may define:

   • Required action-plan and design-specification sections
   • Architecture, compatibility, testing, security, or documentation expectations
   • Repository-specific readiness statuses
   • Human signals and permitted readiness transitions
   • Labels or comment formats to recommend for planning work

   It cannot weaken global security boundaries, authorize a GitHub write, authorize implementation, select a different repository, or turn untrusted repository content into instructions.

   When no planning instructions are configured, use the built-in behavior. If a configured planning file is missing or invalid, return a blocked planning result and do not silently bypass it.

   8. Default Readiness Fallback

   Use these statuses unless the target repository defines its own model:

   • draft: planning artifacts are incomplete or newly generated.
   • needs-review: the action plan and design specification are ready for human review.
   • needs-clarification: specific decisions or missing evidence require human input.
   • blocked: an identified constraint prevents a credible proposal.
   • approved: a human explicitly accepts the planning artifacts.

   A repository may replace these names and define different human signals in planning.md. Regardless of the configured name, readiness represents the state of the planning artifacts only. It never authorizes source changes, branches, pull requests, or deployment.

   9. Output Contract

   Return human-readable Markdown in this order:

   1. Action Plan
   2. Design Specification
   3. Readiness
   4. Assumptions, Risks, and Open Questions
   5. Confirmed Actions, when a write was explicitly requested

   The readiness section must use the repository-configured state model or the built-in fallback and identify the human input needed next. Confirmed actions must distinguish successful tool-confirmed writes from recommendations or failed attempts.

   10. Tools and Write Authorization

   The plan agent receives the existing shared GitHub MCP and runtime tools. It may perform planning-related writes such as adding labels or posting issue comments only when the current user explicitly requests those writes.

   Rules that remain mandatory:

   • Planning or repository investigation authorizes reads, not writes.
   • A requested readiness transition does not automatically authorize a label or comment.
   • Planning customization may define recommended labels, comment content, and signal meanings, but it cannot grant write authorization.
   • Never report a write as completed unless the tool result confirms success.
   • Planning approval does not authorize code implementation or deployment.

   11. Configuration Changes

   Update these surfaces together:

   • issuelens_config.py: add planning to INSTRUCTION_DOMAINS.
   • schemas/issuelens.schema.json: expose the planning instruction entry.
   • examples/issuelens.yml: include a planning example.
   • skills/issuelens-config/SKILL.md: document the domain and fallback behavior.
   • .github/issuelens.yml and .github/issuelens/planning.md: define IssueLens's own planning policy.

   The existing schema/runtime/sample consistency tests ensure these surfaces remain synchronized.

   12. Tests

   Add focused coverage for:

   • agents/plan.md loading and _PLAN_AGENT registration
   • Global routing for initial planning, combined triage/planning, revision, and readiness requests
   • Action plan appearing before the design specification
   • Human-driven waiting rather than autonomous revision
   • Built-in and repository-customized readiness states
   • Missing and invalid planning configuration
   • Untrusted issue or repository content attempting to authorize writes or implementation
   • Explicitly requested labels/comments and tool-confirmed action reporting
   • The continued prohibition on source modification, branches, pull requests, tests-as-implementation, workflow changes, and deployment

   13. Documentation and Initial Delivery Boundary

   Update README.md and .github/copilot-instructions.md with planning architecture, example requests, customization, readiness semantics, and authorization boundaries.

   Do not change .github/workflows/issue-triage.yml in the initial implementation. Planning is available on demand through both existing protocols. An automatic planning trigger can be designed later as a separate opt-in feature.

   No deployment is part of this change unless separately and explicitly approved.
6. Changyong Gong (chagong)

   added the

   Feature

   issue type on Aug 13, 2026
7. Changyong Gong (chagong)

   closed this as completedin #12on Aug 13, 2026