Big News: Socket raises $60M Series C at a $1B valuation to secure software supply chains for AI-driven development.Announcement →
Sign In

agestra

Package Overview
Dependencies
Maintainers
1
Versions
56
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

agestra - npm Package Compare versions

Comparing version
4.15.0
 to
4.15.1
+1
-1
.claude-plugin/marketplace.json

@@ -15,3 +15,3 @@ {

"description": "Multi-host MCP orchestration across Claude, Ollama, Gemini, and Codex for review, QA, and cross-validation",
"version": "4.15.0",
"version": "4.15.1",
"author": {

@@ -18,0 +18,0 @@ "name": "mua-vtuber"

+1
-13
.claude-plugin/plugin.json
{
"name": "agestra",
"version": "4.15.0",
"version": "4.15.1",
"description": "Claude Code plugin — multi-host MCP orchestration across Claude, Ollama, Gemini, and Codex for review, QA, and cross-validation",

@@ -12,15 +12,3 @@ "mcpServers": {

}
},
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/user-prompt-submit.js"
}
]
}
]
}
}
+5
-6
.gemini/commands/agestra/research.toml
# Generated by Agestra. Managed file.
description = "Run research using a selected investigation topology"
description = "Run host-owned Agestra research with an idea, QA, or security viewpoint"
prompt = """
You are executing the `/agestra research` Gemini command.
- Start with `setup_status`, then `environment_check` and `provider_list`.
- For investigation-including workflows that continue into workflow consensus, route through `agent_research_start`, then start debate separately with `agent_consensus_start`.
- Host research/debate contract uses workflow profiles, `aggregation`, `questionSet`, and `evidencePolicy`:
- Start with `setup_status`; provider availability is not a gate for research.
- Ask for the research viewpoint when missing: Idea exploration, QA evidence set, or Security evidence set.
- Use host-owned `agestra-research` assignments. Do not ask for a research topology or provider investigation mode.
- Host research contract uses workflow profiles, `aggregation`, `questionSet`, and `evidencePolicy`:
호스트가 조사한다.
호스트가 정리한다.
시스템이 토론한다.
호스트가 문서화한다.
- External AI research and debate run in separate fresh sessions, even when the same provider participates in both phases.
@{commands/research.md}
"""
+17
-5
AGENTS.md

@@ -33,8 +33,7 @@ # Agestra for Codex

- Public slash commands are limited to setup, research, and review.
- Setup and research requests follow `commands/setup.md` and `commands/research.md`.
- When Agestra is active, review requests follow `commands/review.md`
- When Agestra is active, QA / verification requests follow `commands/qa.md`
- When Agestra is active, security audit requests follow `commands/security.md`
- Internal QA, security, design, idea, and planning viewpoints remain available through workflow profiles and skill/lens resources; they are not shipped as public slash commands.
- Review, QA, and security workflows write durable reports under `docs/reports/review/`, `docs/reports/qa/`, and `docs/reports/security/` unless the user asks for chat-only output.
- When Agestra is active, design and architecture requests follow `commands/design.md`
- When Agestra is active, idea discovery requests follow `commands/idea.md`

@@ -45,3 +44,3 @@ ## Core MCP Tools

- `agent_research_start`: research-only preprocessing with workflow profile, prompt pack, questionSet, evidencePolicy, research lenses, and investigator assignments; writes `research_submissions.json`, `research_transcript.json`, and `aggregation.json`; does not start debate
- `agent_consensus_start` (with `agent_debate_approve`/`_continue`/`_reject`) and `agent_debate_review`: debate-only approval-gated consensus flows from prepared `aggregation`, supplied `questionSet`, and `evidencePolicy`; `workflow` is a report/artifact label only, not a debate routing branch
- `agent_consensus_start` (with `agent_debate_approve`/`_continue`/`_reject`): debate-only approval-gated consensus flows from prepared `aggregation`, supplied `questionSet`, and `evidencePolicy`; `workflow` is a report/artifact label only, not a debate routing branch
- `host_assets_status`, `host_assets_install`, `host_assets_uninstall`: inspect and explicitly manage generated Codex host-native assets such as custom agents and skills

@@ -55,1 +54,14 @@ - `qa_run`: run workspace build/test verification for QA evidence

- `GEMINI.md` and `.gemini/commands/`: Gemini-specific host assets; keep behavior aligned with them when updating shared workflows
## graphify
This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
When the user types `/graphify`, invoke the `skill` tool with `skill: "graphify"` before doing anything else.
Rules:
- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
- Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it.
- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).
+21
-28
agents/agestra-debate.md

@@ -6,3 +6,3 @@ ---

workflow profile/lens context, answers a pending host turn by the supplied
question set, and returns the required consensus JSON. It is not the
question set, and returns the required [ITEM] markup. It is not the
moderator, not the team lead, not a reviewer/QA/security specialist identity,

@@ -22,3 +22,3 @@ and does not choose participants or run rounds.

consensus turn, inspect only the supplied packet/files/lens references, and
return the required JSON answer for that turn.
return the required [ITEM] answer for that turn.

@@ -57,36 +57,29 @@ You are not the consensus engine, moderator, team lead, reviewer, QA judge,

Do not load every lens by default. The lens narrows the question; it does not
override the pending turn packet or JSON contract.
override the pending turn packet or [ITEM] contract.
</Lens_Policy>
<Output_Contract>
Return JSON only. Do not include prose, Markdown, XML tags, or explanations
outside the JSON object.
Return [ITEM] blocks only. Do not include prose, Markdown, JSON, XML tags, or
explanations outside the item blocks.
Consensus turn shape:
```json
{
"provider": "<pending participant id>",
"round": 1,
"items": [
{
"id": "<assigned item id>",
"questionResults": {
"<verdictField from questionSet>": {
"verdict": "<allowed verdict from questionSet>",
"reason": "short evidence-based reason",
"stanceEvidenceType": "empirical",
"evidenceRefs": ["file:line, artifact path, or item evidence ref"]
}
},
"finalStatus": "<allowed final status from questionSet>",
"adjustedRemedy": "optional remedy adjustment when allowed by the packet"
}
]
}
```text
[ITEM]
id: <assigned item id>
stance: agree
responds_to: <assigned item id>
evidence: file:line, artifact path, or item evidence ref
stanceEvidenceType: empirical
question: <questionId> | <verdictField> | <allowed verdict> | short evidence-based rationale
finalStatus: <allowed final status from questionSet>
adjustedRemedy: optional remedy adjustment when allowed by the packet
text:
Concise participant response text.
[/ITEM]
```
Rules:
- `provider` must exactly match the pending participant id.
- `round` must exactly match the pending round.
- The mailbox turn id, participant id, and round are supplied by the packet and
submission tool call; do not invent different values.
- Answer every assigned item exactly once.

@@ -98,3 +91,3 @@ - Answer every required question in the supplied `questionSet`.

security, design, idea, or planning rules.
- Do not create new top-level fields unless the engine contract explicitly allows them.
- Do not return debate JSON.
</Output_Contract>

@@ -101,0 +94,0 @@ 

+54
-114
agents/agestra-team-lead.md

@@ -12,6 +12,6 @@ ---

commands, or natural-language Agestra / multi-AI / provider requests. Those
requests must enter through `agestra-leader` or the selected workflow
skill/command first so workflow profiles, questionSets, mode gates, trust
gates, QA depth gates, and research-topology gates can run before team-lead
execution.
requests must enter through one of the public workflow commands or installed
workflow skills (`/agestra setup`, `/agestra research`, `/agestra review`)
first so workflow profiles, questionSets, mode gates, trust gates, and
evidence-depth gates can run before team-lead execution.

@@ -24,3 +24,3 @@ Plain review/QA/check requests without `/agestra` or explicit multi-AI/provider

codexSandboxMode: read-only
tools: Read, Glob, Grep, Bash, WebFetch, WebSearch, TodoWrite, AskUserQuestion, Skill, ToolSearch, CronCreate, CronList, CronDelete, Agent, mcp__plugin_agestra_agestra__environment_check, mcp__plugin_agestra_agestra__provider_list, mcp__plugin_agestra_agestra__provider_health, mcp__plugin_agestra_agestra__provider_readiness, mcp__plugin_agestra_agestra__provider_trust_apply, mcp__plugin_agestra_agestra__run_observable_events, mcp__plugin_agestra_agestra__trace_query, mcp__plugin_agestra_agestra__trace_summary, mcp__plugin_agestra_agestra__trace_visualize, mcp__plugin_agestra_agestra__ai_chat, mcp__plugin_agestra_agestra__ai_analyze_files, mcp__plugin_agestra_agestra__ai_compare, mcp__plugin_agestra_agestra__agent_research_start, mcp__plugin_agestra_agestra__agent_consensus_start, mcp__plugin_agestra_agestra__agent_debate_status, mcp__plugin_agestra_agestra__agent_consensus_submit_turn, mcp__plugin_agestra_agestra__agent_debate_approve, mcp__plugin_agestra_agestra__agent_debate_continue, mcp__plugin_agestra_agestra__agent_debate_reject, mcp__plugin_agestra_agestra__agent_cross_validate, mcp__plugin_agestra_agestra__workspace_create_document, mcp__plugin_agestra_agestra__workspace_read, mcp__plugin_agestra_agestra__workspace_list
tools: Read, Glob, Grep, Bash, WebFetch, WebSearch, TodoWrite, AskUserQuestion, Skill, ToolSearch, CronCreate, CronList, CronDelete, Agent, mcp__plugin_agestra_agestra__environment_check, mcp__plugin_agestra_agestra__provider_list, mcp__plugin_agestra_agestra__provider_health, mcp__plugin_agestra_agestra__provider_readiness, mcp__plugin_agestra_agestra__provider_trust_apply, mcp__plugin_agestra_agestra__run_observable_events, mcp__plugin_agestra_agestra__trace_query, mcp__plugin_agestra_agestra__trace_summary, mcp__plugin_agestra_agestra__trace_visualize, mcp__plugin_agestra_agestra__ai_chat, mcp__plugin_agestra_agestra__ai_analyze_files, mcp__plugin_agestra_agestra__ai_compare, mcp__plugin_agestra_agestra__agent_research_start, mcp__plugin_agestra_agestra__agent_consensus_start, mcp__plugin_agestra_agestra__agent_debate_status, mcp__plugin_agestra_agestra__agent_consensus_submit_turn, mcp__plugin_agestra_agestra__agent_consensus_next_turn, mcp__plugin_agestra_agestra__agent_consensus_claim_turn, mcp__plugin_agestra_agestra__agent_consensus_heartbeat, mcp__plugin_agestra_agestra__agent_consensus_turn_status, mcp__plugin_agestra_agestra__agent_debate_approve, mcp__plugin_agestra_agestra__agent_debate_continue, mcp__plugin_agestra_agestra__agent_debate_reject, mcp__plugin_agestra_agestra__agent_cross_validate, mcp__plugin_agestra_agestra__workspace_create_document, mcp__plugin_agestra_agestra__workspace_read, mcp__plugin_agestra_agestra__workspace_list
---

@@ -41,8 +41,12 @@

provider context, and the relevant workflow gates, do not run setup checks,
provider checks, consensus, or fan-out. Route back through `agestra-leader` or
the selected workflow skill/command. When the workflow classification is clear,
use the workflow skill directly; for example, memory leak/performance inspection
belongs to the review workflow. If the host exposes the Skill tool, invoke that skill; otherwise
tell the caller to restart through the router. Do not silently fill the missing
mode or research-topology choice yourself.
provider checks, consensus, or fan-out. Route back through the selected public
workflow command or installed workflow skill. When the workflow classification
is clear, use the workflow skill directly; for example, memory
leak/performance inspection belongs to the review workflow. If the host exposes
the Skill tool, invoke that skill; otherwise tell the caller to restart through
`/agestra setup`, `/agestra research`, or `/agestra review`. Do not silently
fill the missing mode yourself. Public `/agestra` handoffs are limited to setup,
research, and review. QA, security, design, idea, and planning concerns arrive
as workflow profiles, lenses, or rubrics inside research/review packets, not as
public command variants.

@@ -112,3 +116,3 @@ Plain review/QA/check requests without `/agestra` or explicit multi-AI/provider wording stay with the current host.

4. Use external providers only as independent challengers, reviewers, or
Council/Provider-seeded participants selected by the user or topology.
consensus participants after host-owned evidence has been prepared.

@@ -186,33 +190,14 @@ Never treat `claude-host` sampling failure as a reason to fall back to

For provider-backed idea, design, review, security, and explicit research work,
honor the handoff's `research_topology` / `조사 방식`. Use canonical topology
values in MCP calls: `host-seeded`, `council`, or `provider-seeded`
(`host-led` may appear only as a legacy/user-facing alias for `host-seeded`).
For renewed public `/agestra research` and `/agestra review` handoffs, research
is host-owned by default. Create focused host-native `agestra-research`
assignments from the selected viewpoint, lenses, and research notes, then
continue. Do not ask the user to choose investigation routes or provider modes.
- `host-seeded`: Host-native first. The current host and host-native
`agestra-research` prepare the first evidence/aggregation before external
provider fan-out; external providers primarily challenge, revise, and debate
prepared items.
- `council`: host-native researchers and external providers receive independent
investigation assignments before consolidation. Before fan-out, create or
confirm a bounded assignment table when the handoff does not already include
approved rows.
- `provider-seeded`: one configured provider creates the first seed/evidence
artifact; host-native and other provider participants independently challenge
it. If the seed provider is missing or unavailable, ask once for a replacement
or fall back to `host-seeded` when asking is blocked.
- `automatic`: choose the lightest topology that preserves quality. Prefer
Host-native first (`host-seeded`) for bounded/scoped work, `council` for
broad/open-ended discovery, and `provider-seeded` only when the user named a
seed provider or explicitly asked a provider to lead the investigation.
External providers are debate challengers, reviewers, or consensus participants
after host research has been prepared. They are not research investigators for
renewed public research/review unless an explicit internal handoff outside these
public commands sets `allow_external_research_investigators: true` and provides
approved assignment rows. Never repair a missing public handoff by asking the
user to select an investigation route.
If provider-backed work needs a research topology but the handoff omitted it,
the team-lead MUST stop and run a mandatory design selection gate before any
provider fan-out. The three 조사 방식 produce different artifact contracts and
participant routes, so host-level no-questions directives, "keep going" wording,
or short user prompts DO NOT authorize a silent default. Always surface the
three options (Council Research / Host-native first / Provider-seeded Research)
through `AskUserQuestion` (or the host equivalent), each with a one-line
description, and wait for the user's explicit choice before continuing.
Use `agent_research_start` when the task needs investigation before provider

@@ -274,6 +259,6 @@ consensus. Research start receives the workflow profile, prompt pack,

- Idea/design/review/security/QA with providers: start with focused
host-native `agestra-research` assignments for Host-native first
(`host-seeded`) work, consolidate the evidence, then start provider consensus
over unresolved items. Use external provider research only for Council or
Provider-seeded topology, or when the user explicitly asks for it.
host-native `agestra-research` assignments, consolidate the evidence, then
start provider consensus over unresolved items. Use external provider
research only when an explicit internal handoff permits it; do not offer
route choices in renewed public workflows.
- Code-changing requests with providers: do not run them as a primary Agestra

@@ -283,3 +268,3 @@ workflow. Explain that the current host should implement first, then Agestra

- Host participant needed in consensus: add an explicit host-turn participant
routed to `agestra-debate`; submit its JSON answer with
routed to `agestra-debate`; submit its [ITEM] markup answer with
`agent_consensus_submit_turn`.

@@ -304,61 +289,27 @@ </Team_Composition>

Across all three QA topologies — Council QA, Host-native first QA,
Provider-seeded QA — browser/dev-server/runtime flows remain host-owned, and
external providers cross-check artifacts only. Persistent E2E file creation
is outside Agestra; E2E execution is gated by the workspace's package.json
scripts.e2e entry.
QA is not a public `/agestra` command. It appears as a review or research
profile/lens/rubric, with host-owned runtime evidence first and external
providers used afterward for debate, rebuttal, or reinforcement. Do not ask the
user to choose a QA route.
Browser/dev-server/runtime flows remain host-owned, and external providers
cross-check artifacts only. Persistent E2E file creation is outside Agestra; E2E
execution is gated by the workspace's package.json scripts.e2e entry.
</QA_Boundary>
<QA_Topology_Execution>
For `/agestra qa`, the handoff packet's `topology` field is authoritative.
Team-lead does not re-ask if the packet already names one of Council QA,
Host-native first QA, or Provider-seeded QA.
<QA_Evidence_Execution>
When a review/research workflow includes a QA lens:
If the handoff packet omits topology, team-lead MUST stop and run a mandatory
design selection gate before any provider fan-out. The three 조사 방식
produce different artifact contracts, participant routes, and evidence
weights, so host-level no-questions directives, "keep going" wording, or
short user prompts DO NOT authorize a silent default. Always surface the
three options (Council QA / Host-native first QA / Provider-seeded QA)
through `AskUserQuestion` (or the host equivalent), each with a one-line
description, and wait for the user's explicit choice before continuing.
A host-only fallback is not a routing option for QA. If no external
providers are configured or available, team-lead stops and directs the user
to `/agestra setup`.
Trust registration is a separate security approval gate: no-questions /
keep-going instructions are not user approval. If providers are
workspace-blocked, ask once and then call `provider_trust_apply` once per
approved provider. Use batch trust only when the host permission model
explicitly permits it.
### Council QA
1. Select the QA workflow profile and call `agent_research_start`.
2. Assign the 6 QA lenses to participants: executable evidence,
spec-to-code compliance, integration risk, edge/error states, test
adequacy, safety hygiene.
3. Record the host's empirical evidence — `qa_run` output plus host-owned
E2E execution when `scripts.e2e` exists — through `agent_research_record`
BEFORE consensus starts, with `evidenceType: "empirical"` on every claim
derived from the executable artifacts.
4. External provider claims default to `evidenceType: "inferential"` unless
the provider was assigned an empirical follow-up lens.
5. Inherit research's council defaults for `max_rounds`.
### Host-native first QA
1. Run `qa_run` plus host-owned E2E execution when `scripts.e2e` exists
(gated by the workspace `package.json` `scripts.e2e` entry; absent
means E2E is skipped with a reason recorded).
2. Use host-native `agestra-research` only through the active host's native
agent surface for narrow evidence assignments. Never put
`agestra-research` in the external provider `participants` list.
2. Use host-native `agestra-research` through the active host's native agent
surface for narrow evidence assignments. Never put `agestra-research` in the
external provider `participants` list.
3. Prepare `aggregation.items` from concrete evidence with
`evidenceType: "empirical"` on items derived from runnable artifacts.
4. Call debate-only `agent_consensus_start` with `workflow: "qa"`, the QA
`questionSet`, `aggregation`, `evidencePolicy`, exact provider participants, optional
`participant_routes` for a host-native `agestra-debate` participant,
`max_rounds: 1`, and a bounded participant timeout.
4. Call debate-only `agent_consensus_start` with the selected workflow label,
questionSet, aggregation, evidencePolicy, exact provider participants,
optional `participant_routes` for a host-native `agestra-debate` participant,
and bounded round/timeout settings.
5. External provider stances on host empirical items default to

@@ -368,17 +319,8 @@ `evidenceType: "inferential"`; `"mixed"` only when the provider cites an

### Provider-seeded QA
Trust registration is a separate security approval gate: no-questions /
keep-going instructions are not user approval. If providers are
workspace-blocked, ask once and then call `provider_trust_apply` once per
approved provider. Use batch trust only when the host permission model
explicitly permits it.
1. Run the selected `seed_provider` first and record its claims with
`evidenceType: "inferential"`.
2. Run the host's empirical evidence pass — `qa_run` plus host-owned E2E
execution when `scripts.e2e` exists — and append host claims with
`evidenceType: "empirical"`. Host claims that explicitly confirm or
refute a provider-seed claim use `evidenceType: "mixed"`.
3. Call debate-only `agent_consensus_start` with `workflow: "qa"`, the QA
`questionSet`, `aggregation`, `evidencePolicy`, the seed provider + at least
one reviewer + the host-debate participant route, `max_rounds: 1`, and a
bounded participant timeout.
### Evidence-type policy (all three topologies)
Every QA claim carries `evidenceType`. Host empirical claims include an

@@ -389,4 +331,2 @@ `evidence_ref` (e.g., `docs/reports/qa/.../qa_run.log#L42-L58`). Two

### Host-native + progress routing (all three topologies)
Never substitute `agestra-research` with an external CLI provider; route any

@@ -401,3 +341,3 @@ host-debate participant via `participant_routes` to `agestra-debate`. Poll

`agent_consensus_submit_turn`.
</QA_Topology_Execution>
</QA_Evidence_Execution>

@@ -404,0 +344,0 @@ <Completion_Report>

+107
-297
commands/research.md
---
description: "Run workflow-profile research with Host-native first, council, or provider-seeded topology"
argument-hint: "[domain] [topic or question]"
description: "Run host-owned Agestra research with an idea, QA, or security viewpoint"
argument-hint: "[idea|qa|security] [topic, target, file, directory, or question]"
---

@@ -10,345 +10,155 @@

Use the user-facing term "조사 방식" when talking to the user.
Provider-facing prompts stay English; user-facing summaries follow the configured locale.
External provider research prompts must include `skills/references/lenses/research-provider-rules.md`.
User-facing text follows the configured setup language. Provider-facing prompt
fragments, JSON keys, enum values, and artifact names stay English.
This command is host-owned research. Do not ask the user to choose a research
topology or provider investigation mode. External providers do not investigate
in this command. If the user wants multiple providers to debate or challenge
research results, finish this research run first, then recommend `/agestra
review` with the desired viewpoint.
## Step 0: Setup preflight
Call `setup_status` first. If setup is required, run the setup workflow, then resume this command with the original request.
Call `setup_status` first. If setup is required, run the setup workflow, then
resume this command with the original request.
Then call `environment_check` and `provider_list` before proposing any multi-provider plan.
Use setup locale for the final Markdown report and user-visible summaries.
Provider availability is not a gate for `/agestra research`; do not stop because
no external provider is configured.
Before any provider fan-out, run the shared workspace trust preflight for the exact current project root. If supported providers are blocked, ask once whether to register only this project folder. This is a security approval gate, not a clarifying question; "keep going" / no-questions instructions are not approval. After approval, call `provider_trust_apply` once per blocked provider. Use `provider_trust_apply_all` only when the host permission model explicitly allows batch trust changes. If approval cannot be obtained, skip blocked providers.
## Step 1: Choose Research Viewpoint
## Step 1: Clarify research target domain and topic
If the request does not clearly state a viewpoint, ask one concise question.
Use these choices:
The research target domain is required. Valid research target domains:
| Option | Use when |
| --- | --- |
| **Idea exploration** | The user wants product/project ideas, improvement candidates, prior art, or user-pain discovery. |
| **QA evidence set** | The user wants evidence for whether an implementation matches a plan, spec, progress note, or expected behavior. |
| **Security evidence set** | The user wants trust-boundary, secret, auth, command/file/network, dependency, privacy, or hardening evidence. |
- `idea`
- `design`
- `review`
- `qa`
- `security`
- `research`
Record the internal target domain as:
If the request does not clearly state a research target domain, ask one concise question before any provider fan-out.
Do not default to `review`.
- `idea` for Idea exploration
- `qa` for QA evidence set
- `security` for Security evidence set
Important boundary:
Do not present provider fan-out, topology, or old mode choices to the user.
```text
호스트가 조사한다.
호스트가 정리한다.
시스템이 토론한다.
호스트가 문서화한다.
```
## Step 2: Clarify Brief
- Standalone `/agestra research` produces research artifacts and a human report; it does not create a bundled participant for a later domain debate.
- When research should continue into idea/design/review/security/qa consensus, hand off to team-lead to call `agent_research_start` for the target workflow, inspect `aggregation.json`, then start debate separately with `agent_consensus_start`.
- External AI research and debate run in separate fresh sessions, even when the same provider participates in both phases.
Collect only missing fields:
Also capture:
- topic or research question
- topic, target, file, directory, document, or question
- target workspace root when relevant
- files/docs/sources to inspect
- freshness requirement when web/current information matters
- output language from setup locale unless the user overrides it
- freshness/current-information requirement
- constraints and exclusions
- desired report language if different from setup locale
## Step 2: Choose or propose 조사 방식
Then load the common research lens plus the selected domain pack:
Available 조사 방식:
- Common: `skills/references/lenses/research.md`
- Idea: `skills/references/lenses/research-domains/idea.md`
- QA: `skills/references/lenses/research-domains/qa.md`
- Security: `skills/references/lenses/research-domains/security.md`
- Council Research
- Host-native first (recorded internally as `host-seeded`)
- Provider-seeded Research
Use the selected domain pack as the question guide. Ask follow-up questions only
when the brief is still too broad to assign focused host research.
If the user already chose one in the request, validate that it fits the domain and continue.
Otherwise this is a mandatory design selection gate. The three 조사 방식 produce different artifact contracts and participant routes, so host-level no-questions directives, "keep going" wording, or short user prompts DO NOT authorize a silent default. Always present the three options through `AskUserQuestion` (or the host equivalent), each with a one-line description, and wait for the user's explicit choice before any provider fan-out.
If no external providers are available, stop Agestra orchestration and tell the user to run setup or handle the research directly outside Agestra.
## Step 3: Plan Host Research
Host-native first means the active host's native `agestra-research` agent creates the first seed/evidence document, persists it through workspace document tooling, and external participants challenge it through the supplied research workflow profile and question set. Record it internally as `host-seeded`. It is provider-backed research, not a host-only multi-AI mode.
Create a concise host-owned assignment table. Each row should include:
Provider-seeded Research means the selected `seed_provider` creates the first seed/evidence artifact, then reviewer participants independently challenge that seed. The seed provider never commands reviewers; Agestra team-lead/moderator remains the orchestrator.
- `item_id`
- `domain`
- `lens`
- `question`
- `scope`
- `deliverable`
- `expected_artifact`
- optional `rationale`
## Step 3: Research plan before fan-out
Split broad work into several narrow `agestra-research` assignments. Good
splits are prior art, user pain, codebase evidence, risk, validation, and
current information when freshness matters.
Before any provider fan-out, create a concise plan containing:
The canonical flow is:
- research target domain
- workflow-profile investigation items
- runtime lenses and roles
- participant assignment table with explicit `domain`, `role`, `lens`, `question`, `deliverable`, and `expected_artifact` values
- expected JSON artifacts
- Markdown report target
- validation step, including finding-validator when claims need confirmation
```text
호스트가 조사한다.
호스트가 정리한다.
호스트가 문서화한다.
```
External provider research prompts must be assembled from provider rules, the
common research guide, the target-domain research card, the `ResearchSubmission`
output contract, and the assignment task packet. Do not send the full
`agestra-research` agent or skill document to providers.
There is no provider fan-out phase in `/agestra research`.
For Council Research, this proposal is mandatory. Ask the user to approve or modify it before running the council.
Do not start provider fan-out until the user approves or modifies the plan.
## Step 4: Execute Host Research
For Host-native first (`host-seeded`), create the host seed/aggregation through the active host's native agent surface before provider fan-out. Normalize it into `aggregation.items`; do not pass it through legacy source-document fields.
Use the active host's native `agestra-research` agent for each focused research
assignment when available. The same agent definition may be run multiple times
with different lenses. External AI providers, local models, and CLI providers
are not canonical research investigators in this command.
Host-native first requires at least one external reviewer participant outside the seed provider. If the user explicitly asks for host-only artifact capture, use `artifact_only_diagnostic: true` and clearly state that no multi-AI consensus was produced.
When the MCP research runner is used, call `agent_research_start` with:
For Provider-seeded Research, choose or confirm one configured and available `seed_provider` before fan-out. Include it in `participants`, include at least one reviewer participant, and pass `reviewer_participants` when the reviewer set should be explicit. Use `seed_scope` when the seed artifact needs a narrower brief. Use `tool_broker_policy` only to record explicit host-brokered evidence expectations (`none`, `host-brokered-readonly`, or `host-brokered-evidence`); this does not grant direct host tool-use to the provider.
- `workflow`: the target domain (`idea`, `qa`, or `security`)
- `target`: the topic/target from the brief
- `researchLenses`: selected lens names
- `investigators`: host-native `agestra-research` assignment rows only
- `promptPack`: common research guide, selected domain pack, and the
`ResearchSubmission` output contract
- `files`: bounded file/document context when relevant
## Step 4: Execute through team-lead
Hand off to `agestra:agestra-team-lead` with a self-contained packet:
- Workflow domain: `research`
- Research target domain: the required target domain from Step 1
- 조사 방식: selected topology
- Topic/question
- Investigation items
- Runtime lens/role assignment table
- Available providers
- Requested providers from user wording, or all available
- Host-native route: for Host-native first (`host-seeded`), run active-host `agestra-research` before external provider fan-out; route any host debate participant to `agestra-debate` with `participant_routes`; do not substitute the current host's external CLI provider for this native role
- Locale
- Target workspace root
- Required JSON artifacts
- Progress contract: surface concise phase updates every 30-60 seconds; poll `agent_debate_status` or `run_observable_events` with a cursor when available; if trace is `cold-start`, report the current local phase and keep monitoring
- Original user request verbatim
For Council Research, the team-lead must call `agent_research_start` first. Debate starts only after approval and after inspecting `aggregation.json`:
`agent_research_start` is research-only. It receives the selected workflow profile,
`agent_research_start` is research-only. It receives the workflow profile,
prompt pack, `questionSet`, `evidencePolicy`, research lenses, and investigator
assignments, then writes `research_submissions.json`,
`research_transcript.json`, and `aggregation.json`. It does not start debate.
debate-only `agent_consensus_start` runs from prepared `aggregation`, supplied
`questionSet`, and `evidencePolicy`; `workflow` is a report/artifact label only,
not a debate routing branch.
```json
{
"workflow": "research",
"questionSet": {
"id": "research.findings-and-sources",
"title": "Research findings and sources validation",
"requiredQuestions": [
{
"id": "claim",
"prompt": "Is the research claim specific and answerable?",
"verdictField": "claimVerdict",
"allowedVerdicts": ["yes", "no", "unclear"],
"required": true
},
{
"id": "source",
"prompt": "Is the claim supported by traceable source evidence?",
"verdictField": "sourceVerdict",
"allowedVerdicts": ["yes", "no", "partial", "unclear"],
"required": true
},
{
"id": "conflict",
"prompt": "Are conflicting sources or uncertainties preserved?",
"verdictField": "conflictVerdict",
"allowedVerdicts": ["yes", "no", "not-applicable", "unclear"],
"required": true
},
{
"id": "action",
"prompt": "What follow-up or decision does this finding support?",
"verdictField": "actionVerdict",
"allowedVerdicts": ["decision-ready", "needs-followup", "background-only", "rejected"],
"required": true
},
{
"id": "status",
"prompt": "Should this be accepted, followed up, background context, or rejected?",
"verdictField": "finalStatus",
"allowedVerdicts": ["accepted", "needs_followup", "background", "rejected"],
"required": true
}
],
"finalStatus": {
"field": "finalStatus",
"allowedValues": ["accepted", "needs_followup", "background", "rejected"]
}
},
"aggregation": { "aggregationId": "<approved aggregation id>", "items": [] },
"evidencePolicy": { "preserveItemEvidenceType": true, "preserveStanceEvidenceType": true },
"participants": ["<explicit-consensus-participant>"]
}
```
If the host directly performs and summarizes the research without the MCP
runner, record the host-owned evidence through `agent_research_record` after
the Markdown report body exists. Include:
For Host-native first (`host-seeded`), the team-lead must first create the host aggregation, then call `agent_consensus_start` with:
- `research_target_domain`
- Markdown report path/body
- research plan and assignment table
- claims with evidence refs and validation status
- available providers when known
- why provider fan-out was not invoked
```json
{
"workflow": "research",
"participants": ["host-seed", "<external-reviewer>"],
"questionSet": {
"id": "research.findings-and-sources",
"title": "Research findings and sources validation",
"requiredQuestions": [
{
"id": "claim",
"prompt": "Is the research claim specific and answerable?",
"verdictField": "claimVerdict",
"allowedVerdicts": ["yes", "no", "unclear"],
"required": true
},
{
"id": "source",
"prompt": "Is the claim supported by traceable source evidence?",
"verdictField": "sourceVerdict",
"allowedVerdicts": ["yes", "no", "partial", "unclear"],
"required": true
},
{
"id": "conflict",
"prompt": "Are conflicting sources or uncertainties preserved?",
"verdictField": "conflictVerdict",
"allowedVerdicts": ["yes", "no", "not-applicable", "unclear"],
"required": true
},
{
"id": "action",
"prompt": "What follow-up or decision does this finding support?",
"verdictField": "actionVerdict",
"allowedVerdicts": ["decision-ready", "needs-followup", "background-only", "rejected"],
"required": true
},
{
"id": "status",
"prompt": "Should this be accepted, followed up, background context, or rejected?",
"verdictField": "finalStatus",
"allowedVerdicts": ["accepted", "needs_followup", "background", "rejected"],
"required": true
}
],
"finalStatus": {
"field": "finalStatus",
"allowedValues": ["accepted", "needs_followup", "background", "rejected"]
}
},
"aggregation": {
"aggregationId": "<host seed aggregation id>",
"items": [
{ "id": "HOST-SEED", "title": "<claim>", "claim": "<what external reviewers should challenge>", "evidenceType": "empirical" }
]
},
"evidencePolicy": { "preserveItemEvidenceType": true, "preserveStanceEvidenceType": true }
}
```
`agent_research_record` records `run_report.json`, `gate_ledger.json`,
`evidence_packet.json`, and `artifact_index.json`. It does not replace
`agent_research_start` when multiple host research assignments are being run.
For Provider-seeded Research, the team-lead must prepare the seed findings as `aggregation.items`, then call `agent_consensus_start` with selected consensus participants:
## Step 5: Validate And Report
```json
{
"workflow": "research",
"participants": ["<configured-seed-provider>", "<reviewer-provider-or-host-participant>"],
"questionSet": {
"id": "research.findings-and-sources",
"title": "Research findings and sources validation",
"requiredQuestions": [
{
"id": "claim",
"prompt": "Is the research claim specific and answerable?",
"verdictField": "claimVerdict",
"allowedVerdicts": ["yes", "no", "unclear"],
"required": true
},
{
"id": "source",
"prompt": "Is the claim supported by traceable source evidence?",
"verdictField": "sourceVerdict",
"allowedVerdicts": ["yes", "no", "partial", "unclear"],
"required": true
},
{
"id": "conflict",
"prompt": "Are conflicting sources or uncertainties preserved?",
"verdictField": "conflictVerdict",
"allowedVerdicts": ["yes", "no", "not-applicable", "unclear"],
"required": true
},
{
"id": "action",
"prompt": "What follow-up or decision does this finding support?",
"verdictField": "actionVerdict",
"allowedVerdicts": ["decision-ready", "needs-followup", "background-only", "rejected"],
"required": true
},
{
"id": "status",
"prompt": "Should this be accepted, followed up, background context, or rejected?",
"verdictField": "finalStatus",
"allowedVerdicts": ["accepted", "needs_followup", "background", "rejected"],
"required": true
}
],
"finalStatus": {
"field": "finalStatus",
"allowedValues": ["accepted", "needs_followup", "background", "rejected"]
}
},
"aggregation": {
"aggregationId": "<provider seed aggregation id>",
"items": [
{
"id": "PROVIDER-SEED",
"title": "<seed claim>",
"claim": "<what reviewers should challenge>",
"evidenceType": "inferential"
}
]
},
"evidencePolicy": { "preserveItemEvidenceType": true, "preserveStanceEvidenceType": true }
}
```
Validate claims that can be checked:
If the seed provider artifact already exists, convert its supported claims into `aggregation.items` before starting consensus.
- split claims
- define validity and false-positive conditions
- check files/docs/tests/callers/framework behavior when available
- classify as `validated`, `dismissed`, or `needs_human_review`
Team-lead owns provider/host-participant fan-out, consensus coordination, JSON ledger flow, finding-validator phase, and final synthesis.
Write a human Markdown report under `docs/reports/research/` unless the user
explicitly asks for chat-only output. The report should separate:
Runtime boundary: native researcher/helper agents are created only by the active host layer. External providers named in the host-owned assignment plan participate through MCP or chat routes; they do not create, spawn, or manage Claude/Codex/Gemini native agents.
- confirmed findings
- weak or inferential findings
- disputed or contradictory evidence
- dismissed claims
- unknowns and next checks
- recommended next `/agestra review` viewpoint when provider debate would help
This command must not call `agent_consensus_start` directly when external providers are involved until host-owned research preprocessing has produced `aggregation.items`.
This command must not create a bundled research pseudo-participant or carry research bundles through legacy source-document fields.
Expected artifact names when applicable:
When host-owned investigation material is produced as evidence for a provider-backed research workflow, record it through `agent_research_record` before the council or Host-native first (`host-seeded`) review consumes it. Include:
- `research_target_domain`
- selected `topology`
- Markdown report path/body
- claims with evidence refs and validation status
- available providers when known
- how the host evidence will feed provider-backed review or debate
`agent_research_record` is only a host-owned evidence recording helper. It does
not replace `agent_research_start`, `aggregation.json`, or the separate
`agent_consensus_start` debate flow.
## Step 5: Present results
Return:
- `research_submissions.json`
- `research_transcript.json`
- `aggregation.json`
- `debate_transcript.json`
- `workflow_result.json`
- `run_report.json`
- `gate_ledger.json`
- `evidence_packet.json`
- `artifact_index.json`
- threaded aggregation document
- concise final decision document
- Markdown report path
- JSON artifact index path
- run report, gate ledger, and evidence packet paths
- Observable events artifact path and the `run_observable_events` locator hint when available
- individual results, evidence packet, dispute ledger, consensus ledger paths when available
- agreed conclusions
- unique insights
- disputed items
- rejected or dismissed claims
- next recommended `/agestra` command
Do not average away disagreement. Do not claim research is complete without artifact and verification evidence.
Do not claim research is complete without artifact and verification evidence.
+17
-16
commands/review.md

@@ -64,3 +64,4 @@ ---

Do not offer full security audit as a review lens. If the user asks for security, route to `/agestra security`.
Do not route to removed legacy slash commands.
If the user asks for QA, security, design, idea, or planning judgment, keep the entry point as `/agestra review` and record that requested viewpoint in the review lens / workflow-profile handoff.

@@ -82,15 +83,13 @@ Then ask for review depth only if not obvious:

Then ask research notes before provider fan-out: regression-prone areas, blast radius / downstream callers, prior incidents, dependency / supply-chain concerns, current-information needs, or `skip`. Ask whether any provider or lens should receive a specific research assignment, or whether team-lead should choose.
Then ask research notes before provider fan-out: regression-prone areas, blast radius / downstream callers, prior incidents, dependency / supply-chain concerns, current-information needs, or `skip`. Ask whether any review lens should receive a specific host-owned research assignment, or whether team-lead should choose.
## Step 3: Choose 조사 방식
## Step 3: Record host-owned research route
Before provider fan-out, ask once which investigation topology to use unless the user already specified it:
Do not ask the user to choose a research topology or provider investigation mode for `/agestra review`. Review uses host-owned research by default:
| Option | Description |
|--------|-------------|
| **Host-native first (Recommended)** | The active host's native `agestra-research` agent prepares bounded review evidence first; providers challenge and debate the prepared findings. Record internally as `host-seeded`. |
| **Council Research** | Host and providers independently inspect assigned review lenses before consolidation and debate. |
| **Provider-seeded Research** | One selected provider creates the first review seed/evidence artifact; host and other providers challenge it. |
- `research_topology: "host-seeded"`
- `조사 방식: "host-owned"`
- `allow_external_research_investigators: false`
This is a mandatory design selection gate. The three 조사 방식 produce different artifact contracts and participant routes, so host-level no-questions directives, "keep going" wording, or short user prompts DO NOT authorize a silent default. Always present the three options through `AskUserQuestion` (or the host equivalent), each with a one-line description, and wait for the user's explicit choice before any provider fan-out. If Provider-seeded Research is selected and the seed provider is not explicit, record the seed provider as pending; after provider availability is listed, ask which available provider should seed. Do not infer it.
The selected review lenses and research notes drive the active host's `agestra-research` assignments. External providers may challenge and debate the prepared host-owned findings, but they are not research investigators unless an internal/legacy handoff explicitly opts into that behavior outside this public command.

@@ -105,3 +104,3 @@ ## Step 4: Route execution

**Provider-backed path — 1+ external providers available (multi-AI):**
Hand off to the `agestra:agestra-team-lead` agent with multi-AI mode **pre-selected**. Provider-backed review uses the selected research topology flow:
Hand off to the `agestra:agestra-team-lead` agent with multi-AI mode **pre-selected** and review research topology **pre-selected**. Provider-backed review uses the fixed host-owned research flow:

@@ -125,6 +124,8 @@ ```text

- **Workflow profile:** review profile with `workflow: "review"`, review `questionSet`, prompt pack, and `evidencePolicy`
- **Research topology / 조사 방식:** selected in Step 3 (`host-seeded`, `council`, `provider-seeded`, or `automatic`); seed or research findings become `aggregation.items`
- **Host-native route:** for Host-native first (`host-seeded`), run active-host `agestra-research` before external provider fan-out; route any host debate participant to `agestra-debate` with `participant_routes`; do not substitute the current host's external CLI provider for this native role
- **Research topology / 조사 방식:** fixed internal `host-seeded` (`host-owned`); team-lead must NOT re-ask for topology; host research findings become `aggregation.items`
- **Host-native route:** run active-host `agestra-research` before external provider challenge/debate; route any host debate participant to `agestra-debate` with `participant_routes`; do not substitute the current host's external CLI provider for this native role
- **Research lenses:** selected review lenses and optional assignment rows that shape host-owned `agestra-research` work
- **Research notes:** what the selected investigation should look for (regression-prone areas, blast radius, prior incidents, dependency concerns, current-information needs)
- **Research assignments:** optional participant/lens rows for `research_assignments`
- **Research assignments:** optional host-owned lens rows for `research_assignments`
- **External research investigators:** `allow_external_research_investigators: false`
- **Available providers:** from `environment_check`; include configured providers when their detected model capability is suitable, using read-only review tools for code/document critique

@@ -141,3 +142,3 @@ - **Requested providers:** explicit names captured from user wording; otherwise "all available review-capable"

- Building the participant team from focused review lenses, explicit host-turn debate participants, and external providers
- Resolving the selected research topology, then calling `agent_research_start` when investigation fan-out is required; call debate-only `agent_consensus_start` only after `aggregation.json` has been inspected and approved.
- Honoring the fixed `host-seeded` research topology without re-asking, then calling `agent_research_start` for host-owned investigation; call debate-only `agent_consensus_start` only after `aggregation.json` has been inspected and approved.
- Ensuring external AI research and debate use separate fresh sessions.

@@ -165,3 +166,3 @@ - Never creating a bundled research pseudo-participant and never carrying research bundles through legacy source-document fields.

- Include the review verdict: APPROVE / APPROVE WITH CONCERNS / BLOCKING CONCERNS
- If QA or security is needed, recommend `/agestra qa` or `/agestra security`
- If QA, security, design, idea, or planning follow-up is needed, recommend another `/agestra review` pass with that explicit viewpoint rather than a removed legacy slash command
- Communicate in the user's language
+33
-17
commands/setup.md

@@ -30,3 +30,3 @@ ---

- Explain this in the user's language.
- Briefly tell the user they need to install at least one supported provider (Ollama, Gemini CLI, Codex CLI, or Claude CLI).
- Briefly tell the user they need to install or run at least one supported provider (Ollama, LM Studio, Gemini CLI, Codex CLI, or Claude CLI).
- Stop without calling `setup_apply`.

@@ -49,4 +49,22 @@

## Step 4: Ask for provider selection
## Step 4: Ask for language
Use AskUserQuestion in the user's language with these choices, or a plain numbered prompt if structured choices are unavailable:
Wait for an explicit language choice before calling `setup_apply`.
| Option | Description |
|--------|-------------|
| **한국어** | Korean UI / moderator text |
| **English** | English UI / moderator text |
| **日本語** | Japanese UI / moderator text |
| **中文** | Chinese UI / moderator text |
Map these to locale codes:
- `한국어` → `ko`
- `English` → `en`
- `日本語` → `ja`
- `中文` → `zh`
## Step 5: Ask for provider selection
Use AskUserQuestion with **multiSelect: true** in the user's language, or a plain numbered prompt with comma/list selection if structured choices are unavailable.

@@ -56,3 +74,3 @@ Wait for an explicit provider selection; do not infer enabled providers from installation alone.

Present one option per currently available provider from `setup_status`.
- Label: provider ID (`ollama`, `gemini`, `codex`, `claude-cli`, etc.)
- Label: provider ID (`ollama`, `lm-studio`, `gemini`, `codex`, `claude-cli`, etc.)
- Description: short capability hint from `provider_list`

@@ -65,22 +83,19 @@

## Step 5: Ask for language
## Step 6: Ask for local AI role when needed
Use AskUserQuestion in the user's language with these choices, or a plain numbered prompt if structured choices are unavailable:
Wait for an explicit language choice before calling `setup_apply`.
If the selected providers include a local AI provider (`ollama` or `lm-studio`), ask one follow-up role question:
| Option | Description |
|--------|-------------|
| **한국어** | Korean UI / moderator text |
| **English** | English UI / moderator text |
| **日本語** | Japanese UI / moderator text |
| **中文** | Chinese UI / moderator text |
| **Advisory** | Include the local AI in transcripts as supplemental opinion, but exclude it from default consensus calculation. Recommended default. |
| **Full debater** | Include the local AI as a formal debate participant after readiness and output-format checks pass. |
Map these to locale codes:
- `한국어` → `ko`
- `English` → `en`
- `日本語` → `ja`
- `中文` → `zh`
Map these to `local_ai_role`:
- `Advisory` → `advisory`
- `Full debater` → `full_debater`
## Step 6: Apply setup
If no local AI provider is selected, do not ask this question; unselected local AI providers are stored as disabled.
## Step 7: Apply setup
Ask the workspace trust policy question once. Default to `ask` unless the user explicitly chooses a different advanced policy:

@@ -98,4 +113,5 @@ - `ask`: ask before registering a new exact project root

- `workspace_trust_policy`: the selected policy, normally `ask`
- `local_ai_role`: only when a selected local AI provider needs a role; default to `advisory` only after the user selected the local AI
## Step 7: Report result
## Step 8: Report result

@@ -102,0 +118,0 @@ Respond in the user's language with:

+1
-1
GEMINI.md

@@ -53,3 +53,3 @@ # Agestra for Gemini CLI

`research_transcript.json`, and `aggregation.json`; does not start debate
- debate-only `agent_consensus_start`, `agent_debate_approve`/`_continue`/`_reject`, `agent_debate_review`: sessions from prepared `aggregation`, supplied `questionSet`, `evidencePolicy`, and approval-gated debate artifacts
- debate-only `agent_consensus_start`, `agent_debate_approve`/`_continue`/`_reject`: sessions from prepared `aggregation`, supplied `questionSet`, `evidencePolicy`, and approval-gated debate artifacts
- `workspace_*`: document-backed review and aggregation flows

@@ -56,0 +56,0 @@ - `qa_run`: workspace build/test verification for QA evidence

+1
-1
package.json
{
"name": "agestra",
"version": "4.15.0",
"version": "4.15.1",
"description": "Multi-host MCP orchestration for Claude Code, Codex CLI, Gemini CLI, and local models",

@@ -5,0 +5,0 @@ "type": "module",

+8
-10
README.ja.md

@@ -24,4 +24,4 @@ # Agestra

- Claude Code: `/agestra review`, `/agestra qa`, `/agestra security`, `/agestra design`, `/agestra idea`
- Gemini CLI: `/agestra:review`, `/agestra:qa`, `/agestra:security`, `/agestra:design`, `/agestra:idea`
- Claude Code: `/agestra research ...` または `/agestra review ...`
- Gemini CLI: `/agestra:research ...` または `/agestra:review ...`
- Codex CLI: `Use Agestra with Gemini and Codex to review this branch.` のように、Agestra や複数 AI を明示して依頼

@@ -33,7 +33,5 @@

- `review`: コード品質、回帰リスク、UX、整理ポイントを複数 AI の視点で比較
- `qa`: 設計書や計画を基準に実装を検証し、PASS/FAIL の根拠を集める
- `security`: セキュリティ観点に絞って確認する
- `design`: 実装前に構造やトレードオフを整理する
- `idea`: 改善案、代替案、類似ツールを探る
- `research`: アイデア、QA、セキュリティの質問に必要な根拠を現在のホストだけで調査し整理します。この流れでは外部 provider は調査しません。
- `review`: 既存のコード、ドキュメント、diff、または準備済みのリサーチ結果をもとに討論し、意見を比較します。レビューは新しい調査を始めません。
- レビュー観点には、コード品質、回帰リスク、UX、整理、設計適合性、性能、信頼性、テスト、安全性のにおい、リリース準備状況を含められます。

@@ -44,7 +42,7 @@ ## 実行すると何が起こるか

2. 依頼を対象とスコープが明確なワークフローに整理します。
3. 調査が必要なら、ホストが先に証拠を集めて整理します。
4. 選ばれた provider は残っている論点だけをレビューまたは討論します。
3. `research` では、現在のホストが根拠を調査し、整理し、文書化します。provider fan-out はありません。
4. `review` では、選ばれた provider がスコープ内のコード、ドキュメント、diff、または準備済みのリサーチ結果について討論します。別途調査はしません。
5. 結論、意見の違い、根拠を 1 つの結果として返します。
普通のレビューや QA の依頼が自動で Agestra になるわけではありません。`/agestra ...` を使うか、複数 AI や provider-backed のレビュー、QA、セキュリティ、設計、アイデア作業を明示したときに Agestra が動きます。
普通のレビューや QA の依頼が自動で Agestra になるわけではありません。`/agestra ...` を使うか、複数 AI や provider-backed のリサーチ/レビュー作業を明示したときに Agestra が動きます。

@@ -51,0 +49,0 @@ コード変更は、まず現在のホストで直接行うのが基本です。Agestra はその後で結果をレビューし、計画との一致を確認し、複数 provider の意見と根拠を記録するところで最も力を発揮します。

+8
-10
README.ko.md

@@ -24,4 +24,4 @@ # Agestra

- Claude Code: `/agestra review`, `/agestra qa`, `/agestra security`, `/agestra design`, `/agestra idea`
- Gemini CLI: `/agestra:review`, `/agestra:qa`, `/agestra:security`, `/agestra:design`, `/agestra:idea`
- Claude Code: `/agestra research ...` 또는 `/agestra review ...`
- Gemini CLI: `/agestra:research ...` 또는 `/agestra:review ...`
- Codex CLI: `Agestra로 Gemini와 Codex를 같이 써서 이 브랜치 리뷰해줘`처럼 Agestra나 여러 AI를 명시해서 요청

@@ -33,7 +33,5 @@

- `review`: 코드 품질, 회귀 위험, UX, 정리 포인트를 여러 AI 의견으로 비교
- `qa`: 설계 문서나 계획 기준으로 구현을 검증하고 PASS/FAIL 근거 수집
- `security`: 보안 관점만 따로 집중해서 검토
- `design`: 구현 전에 구조와 트레이드오프 논의
- `idea`: 개선 아이디어, 대안, 유사 도구 탐색
- `research`: 아이디어, QA, 보안 질문에 필요한 근거를 현재 호스트만 조사하고 정리합니다. 외부 provider는 이 흐름에서 조사하지 않습니다.
- `review`: 이미 있는 코드, 문서, diff, 또는 준비된 리서치 결과를 두고 토론하고 의견을 비교합니다. 리뷰는 새 조사를 시작하지 않습니다.
- 리뷰 관점은 코드 품질, 회귀 위험, UX, 정리, 설계 적합성, 성능, 안정성, 테스트, 기본 안전 냄새, 배포 준비도를 다룰 수 있습니다.

@@ -44,7 +42,7 @@ ## 실행하면 어떻게 되나

2. 요청을 대상과 범위가 분명한 워크플로우로 정리합니다.
3. 조사가 필요하면 호스트가 먼저 근거를 모으고 정리합니다.
4. 선택된 provider들이 남은 쟁점만 검토하거나 토론합니다.
3. `research`에서는 현재 호스트가 근거를 조사하고 정리하고 문서화합니다. provider fan-out은 없습니다.
4. `review`에서는 선택된 provider들이 범위 안의 코드, 문서, diff, 또는 준비된 리서치 결과를 놓고 토론합니다. 별도 조사는 하지 않습니다.
5. 결론, 이견, 근거를 하나의 결과로 돌려줍니다.
평범한 리뷰나 QA 요청이 자동으로 Agestra가 되는 것은 아닙니다. `/agestra ...`를 쓰거나, 여러 AI나 provider-backed 리뷰/QA/보안/설계/아이디어 작업을 명시했을 때 Agestra 워크플로우가 시작됩니다.
평범한 리뷰나 QA 요청이 자동으로 Agestra가 되는 것은 아닙니다. `/agestra ...`를 쓰거나, 여러 AI나 provider-backed 리서치/리뷰 작업을 명시했을 때 Agestra 워크플로우가 시작됩니다.

@@ -51,0 +49,0 @@ 코드 변경은 먼저 현재 호스트에서 직접 진행하는 편이 좋습니다. Agestra는 그 다음 결과를 리뷰하고, 계획과 맞는지 검증하고, 여러 provider 의견과 근거를 기록할 때 가장 강합니다.

+8
-10
README.md

@@ -24,4 +24,4 @@ # Agestra

- Claude Code: `/agestra review`, `/agestra qa`, `/agestra security`, `/agestra design`, `/agestra idea`
- Gemini CLI: `/agestra:review`, `/agestra:qa`, `/agestra:security`, `/agestra:design`, `/agestra:idea`
- Claude Code: `/agestra research ...` or `/agestra review ...`
- Gemini CLI: `/agestra:research ...` or `/agestra:review ...`
- Codex CLI: ask explicitly for Agestra or multiple providers, for example `Use Agestra with Gemini and Codex to review this branch.`

@@ -33,7 +33,5 @@

- `review`: compare multiple AI opinions about code quality, regressions, UX, and cleanup
- `qa`: verify implementation against a design or plan and collect PASS/FAIL evidence
- `security`: run a dedicated security-focused review
- `design`: discuss architecture and tradeoffs before coding
- `idea`: explore improvements, alternatives, and similar tools
- `research`: host-only evidence gathering for idea, QA, or security questions. External providers do not investigate in this flow.
- `review`: debate and compare opinions about existing code, docs, diffs, or prepared research. Review does not start a fresh investigation.
- Review lenses can cover code quality, regressions, UX, cleanup, design fit, performance, reliability, tests, safety smells, and production readiness.

@@ -44,7 +42,7 @@ ## How It Runs

2. It turns your request into a clear workflow with a target and scope.
3. When research is needed, the host gathers and organizes the evidence first.
4. Selected providers review or debate only the unresolved points.
3. In `research`, the current host gathers, organizes, and documents evidence. There is no provider fan-out.
4. In `review`, selected providers discuss the code, documents, diffs, or prepared research already in scope. They do not perform separate research.
5. Agestra returns one result with conclusions, disagreements, and evidence.
Plain review or QA requests do not automatically become Agestra workflows. Agestra starts when you use `/agestra ...` or explicitly ask for multi-AI or provider-backed review, QA, security, design, or idea work.
Plain review or QA requests do not automatically become Agestra workflows. Agestra starts when you use `/agestra ...` or explicitly ask for multi-AI or provider-backed research/review work.

@@ -51,0 +49,0 @@ For code changes, use your current host directly first. Agestra is strongest after that: reviewing the result, checking it against a plan, comparing provider opinions, and recording the evidence.

+8
-10
README.zh.md

@@ -24,4 +24,4 @@ # Agestra

- Claude Code: `/agestra review`, `/agestra qa`, `/agestra security`, `/agestra design`, `/agestra idea`
- Gemini CLI: `/agestra:review`, `/agestra:qa`, `/agestra:security`, `/agestra:design`, `/agestra:idea`
- Claude Code: `/agestra research ...` 或 `/agestra review ...`
- Gemini CLI: `/agestra:research ...` 或 `/agestra:review ...`
- Codex CLI: 像 `Use Agestra with Gemini and Codex to review this branch.` 这样明确提到 Agestra 或多个 AI

@@ -33,7 +33,5 @@

- `review`: 比较多个 AI 对代码质量、回归风险、UX 和整理点的看法
- `qa`: 按设计文档或计划验证实现，并收集 PASS/FAIL 证据
- `security`: 专门做安全视角的检查
- `design`: 在写代码前讨论结构和取舍
- `idea`: 探索改进方向、备选方案和相似工具
- `research`: 由当前宿主单独收集并整理 idea、QA 或安全问题所需的证据。外部 provider 不参与这个调查流程。
- `review`: 围绕已有代码、文档、diff 或已准备好的 research 结果进行讨论并比较意见。review 不会启动新的调查。
- review 视角可以覆盖代码质量、回归风险、UX、整理点、设计契合度、性能、可靠性、测试、安全异味和上线准备度。

@@ -44,7 +42,7 @@ ## 运行时会发生什么

2. 它把请求整理成目标和范围明确的工作流。
3. 如果需要调查，宿主先收集并整理证据。
4. 被选中的 provider 只讨论或审查剩下的未解决问题。
3. 在 `research` 中，当前宿主负责调查、整理并文档化证据。没有 provider fan-out。
4. 在 `review` 中，被选中的 provider 讨论范围内的代码、文档、diff 或已准备好的 research 结果。它们不会另行调查。
5. Agestra 返回一份包含结论、分歧和证据的结果。
普通的 review 或 QA 请求不会自动变成 Agestra 工作流。只有当你使用 `/agestra ...`，或者明确要求多 AI / provider-backed 的 review、QA、安全、设计或 idea 工作时，Agestra 才会启动。
普通的 review 或 QA 请求不会自动变成 Agestra 工作流。只有当你使用 `/agestra ...`，或者明确要求多 AI / provider-backed 的 research/review 工作时，Agestra 才会启动。

@@ -51,0 +49,0 @@ 代码修改应优先由当前宿主直接完成。Agestra 最适合在修改之后审查结果、按计划验证、比较多个 provider 的意见，并记录证据。

+4
-0
scripts/host-assets/categories.mjs

@@ -49,2 +49,6 @@ // Single source of truth for agent permission categories.

"agent_consensus_submit_turn",
"agent_consensus_next_turn",
"agent_consensus_claim_turn",
"agent_consensus_heartbeat",
"agent_consensus_turn_status",
"agent_debate_approve",

@@ -51,0 +55,0 @@ "agent_debate_continue",

+183
-6
scripts/host-assets/codex-assets.mjs

@@ -5,2 +5,4 @@ import fs from "node:fs/promises";

installManagedFiles,
pruneManifestTargets,
removeEmptyDirectory,
resolveAgestraHome,

@@ -12,9 +14,35 @@ uninstallManagedFiles,

export const MANAGED_HEADER = `# ${MANAGED_MARKER}`;
export const PUBLIC_CODEX_SKILL_NAMES = new Set([
"agestra-research",
"agestra-review",
"setup",
]);
export const LEGACY_CODEX_SKILL_DIR_NAMES = new Set([
"agestra-design",
"agestra-e2e",
"agestra-idea",
"agestra-leader",
"agestra-plan",
"agestra-qa",
"agestra-security",
"build-fix",
"cancel",
"e2e",
"leader",
"provider-guide",
"trace",
]);
export const LEGACY_CODEX_AGENT_FILE_NAMES = new Set([
"agestra-designer.toml",
"agestra-e2e-writer.toml",
"agestra-ideator.toml",
"agestra-implementer.toml",
"agestra-moderator.toml",
"agestra-qa.toml",
"agestra-reviewer.toml",
"agestra-security.toml",
]);
export { resolveAgestraHome };
function toCodexAgentName(name) {
return name.replace(/-/g, "_");
}
function toTomlString(value) {

@@ -160,4 +188,142 @@ return JSON.stringify(String(value));

function assertSafeLegacySkillDir({ skillDir, skillsDir, skillName }) {
if (!LEGACY_CODEX_SKILL_DIR_NAMES.has(skillName)) {
throw new Error(`Refusing to clean unknown Codex skill directory: ${skillName}`);
}
const resolvedSkillsDir = path.resolve(skillsDir);
const resolvedSkillDir = path.resolve(skillDir);
if (!resolvedSkillDir.startsWith(`${resolvedSkillsDir}${path.sep}`)) {
throw new Error(`Refusing to clean Codex skill directory outside skills root: ${skillDir}`);
}
}
function assertSafeLegacyAgentFile({ agentFile, agentsDir, fileName }) {
if (!LEGACY_CODEX_AGENT_FILE_NAMES.has(fileName)) {
throw new Error(`Refusing to clean unknown Codex agent file: ${fileName}`);
}
const resolvedAgentsDir = path.resolve(agentsDir);
const resolvedAgentFile = path.resolve(agentFile);
if (!resolvedAgentFile.startsWith(`${resolvedAgentsDir}${path.sep}`)) {
throw new Error(`Refusing to clean Codex agent file outside agents root: ${agentFile}`);
}
}
async function isManagedLegacySkillDir(skillDir) {
const skillFile = path.join(skillDir, "SKILL.md");
let content;
try {
content = await fs.readFile(skillFile, "utf8");
} catch (err) {
if (err?.code !== "ENOENT") throw err;
try {
const entries = await fs.readdir(skillDir);
return entries.length === 0;
} catch (readErr) {
if (readErr?.code === "ENOENT") return false;
throw readErr;
}
}
return content.includes(MANAGED_MARKER);
}
async function isManagedLegacyAgentFile(agentFile) {
try {
const content = await fs.readFile(agentFile, "utf8");
return content.includes(MANAGED_MARKER);
} catch (err) {
if (err?.code === "ENOENT") return false;
throw err;
}
}
export async function cleanupLegacyCodexSkillDirs({
scope = "project",
homeDir = resolveAgestraHome(),
repoRoot = process.cwd(),
} = {}) {
const skillsDir = resolveCodexSkillsDir({ scope, homeDir, repoRoot });
const removed = [];
const skipped = [];
for (const skillName of [...LEGACY_CODEX_SKILL_DIR_NAMES].sort()) {
const skillDir = path.join(skillsDir, skillName);
assertSafeLegacySkillDir({ skillDir, skillsDir, skillName });
if (await isManagedLegacySkillDir(skillDir)) {
await fs.rm(skillDir, { recursive: true, force: true });
removed.push(skillDir);
continue;
}
if (await exists(skillDir)) skipped.push(skillDir);
}
if (removed.length > 0) {
const removedSet = new Set(removed.map((dirPath) => path.resolve(dirPath)));
await pruneManifestTargets(homeDir, (target) => {
if (target.host !== "codex" || target.scope !== scope || target.kind !== "file") {
return false;
}
return [...removedSet].some((dirPath) => path.resolve(target.path).startsWith(`${dirPath}${path.sep}`));
});
await removeEmptyDirectory(skillsDir);
await removeEmptyDirectory(path.dirname(skillsDir));
}
return { removed, skipped };
}
export async function cleanupLegacyCodexAgentFiles({
scope = "project",
homeDir = resolveAgestraHome(),
repoRoot = process.cwd(),
} = {}) {
const agentsDir = resolveCodexAgentsDir({ scope, homeDir, repoRoot });
const removed = [];
const skipped = [];
for (const fileName of [...LEGACY_CODEX_AGENT_FILE_NAMES].sort()) {
const agentFile = path.join(agentsDir, fileName);
assertSafeLegacyAgentFile({ agentFile, agentsDir, fileName });
if (await isManagedLegacyAgentFile(agentFile)) {
await fs.rm(agentFile, { force: true });
removed.push(agentFile);
continue;
}
if (await exists(agentFile)) skipped.push(agentFile);
}
if (removed.length > 0) {
const removedSet = new Set(removed.map((filePath) => path.resolve(filePath)));
await pruneManifestTargets(homeDir, (target) => {
if (target.host !== "codex" || target.scope !== scope || target.kind !== "file") {
return false;
}
return removedSet.has(path.resolve(target.path));
});
await removeEmptyDirectory(agentsDir);
await removeEmptyDirectory(path.dirname(agentsDir));
}
return { removed, skipped };
}
async function exists(filePath) {
try {
await fs.access(filePath);
return true;
} catch (err) {
if (err?.code === "ENOENT") return false;
throw err;
}
}
export function generateCodexAgentToml(role) {
const name = toCodexAgentName(role.name);
const name = role.name;
const description = role.description ?? role.name;

@@ -234,2 +400,7 @@ const sandboxMode = role.sandboxMode ?? "read-only";

export async function loadCodexPublicSkillSpecsFromSkillsDir(skillsDir) {
const skills = await loadCodexSkillSpecsFromSkillsDir(skillsDir);
return skills.filter((skill) => PUBLIC_CODEX_SKILL_NAMES.has(skill.name));
}
export function buildCodexHostAssetFiles({

@@ -288,2 +459,4 @@ scope = "project",

const files = buildCodexHostAssetFiles({ scope, homeDir, repoRoot, roles, skills });
await cleanupLegacyCodexAgentFiles({ scope, homeDir, repoRoot });
await cleanupLegacyCodexSkillDirs({ scope, homeDir, repoRoot });

@@ -303,4 +476,5 @@ return installManagedFiles({

homeDir = resolveAgestraHome(),
repoRoot = process.cwd(),
}) {
return uninstallManagedFiles({
const result = await uninstallManagedFiles({
host: "codex",

@@ -310,2 +484,5 @@ scope,

});
await cleanupLegacyCodexAgentFiles({ scope, homeDir, repoRoot });
await cleanupLegacyCodexSkillDirs({ scope, homeDir, repoRoot });
return result;
}
+110
-7
scripts/host-assets/gemini-assets.mjs

@@ -6,2 +6,3 @@ import fs from "node:fs/promises";

installManagedFiles,
pruneManifestTargets,
removeEmptyDirectory,

@@ -12,5 +13,31 @@ resolveAgestraHome,

const MANAGED_MARKER = "Generated by Agestra. Managed file.";
export const MANAGED_MARKER = "Generated by Agestra. Managed file.";
export const GEMINI_EXTENSION_NAME = "agestra";
const GEMINI_EXTENSION_DESCRIPTION = "Agestra multi-AI orchestration workflows for Gemini CLI.";
const PUBLIC_GEMINI_COMMANDS = new Set([
"agestra/research.toml",
"agestra/review.toml",
"agestra/setup.toml",
]);
const PUBLIC_GEMINI_SKILLS = new Set([
"agestra-research",
"agestra-review",
"setup",
]);
export const LEGACY_GEMINI_ASSET_PATHS = new Set([
".gemini/commands/agestra/design.toml",
".gemini/commands/agestra/idea.toml",
".gemini/commands/agestra/qa.toml",
".gemini/commands/agestra/security.toml",
".gemini/skills/agestra-design/SKILL.md",
".gemini/skills/agestra-e2e/SKILL.md",
".gemini/skills/agestra-idea/SKILL.md",
".gemini/skills/agestra-plan/SKILL.md",
".gemini/skills/agestra-qa/SKILL.md",
".gemini/skills/agestra-security/SKILL.md",
".gemini/skills/build-fix/SKILL.md",
".gemini/skills/cancel/SKILL.md",
".gemini/skills/provider-guide/SKILL.md",
".gemini/skills/trace/SKILL.md",
]);
const GEMINI_AGENT_OMITTED_FRONTMATTER_KEYS = new Set([

@@ -155,2 +182,6 @@ "codexSandboxMode",

function isPublicGeminiCommand(relativeFromCommands) {
return PUBLIC_GEMINI_COMMANDS.has(toForwardSlash(relativeFromCommands));
}
async function expandCommandReferences(content, sourceRoot) {

@@ -239,14 +270,16 @@ const references = [...content.matchAll(/@\{commands\/([^}]+)\}/g)];

function geminiTargetPath({ asset, scope, homeDir, repoRoot }) {
const normalizedRelativePath = toForwardSlash(asset.relativePath);
if (scope === "project") {
return path.join(repoRoot, asset.relativePath);
return path.join(repoRoot, ...normalizedRelativePath.split("/"));
}
if (scope === "user") {
if (asset.relativePath === "GEMINI.md") {
if (normalizedRelativePath === "GEMINI.md") {
return path.join(homeDir, ".gemini", "GEMINI.md");
}
const geminiPrefix = `.gemini${path.sep}`;
if (asset.relativePath.startsWith(geminiPrefix)) {
return path.join(homeDir, ".gemini", asset.relativePath.slice(geminiPrefix.length));
const geminiPrefix = ".gemini/";
if (normalizedRelativePath.startsWith(geminiPrefix)) {
return path.join(homeDir, ".gemini", ...normalizedRelativePath.slice(geminiPrefix.length).split("/"));
}

@@ -258,2 +291,65 @@ }

async function exists(filePath) {
try {
await fs.access(filePath);
return true;
} catch (err) {
if (err?.code === "ENOENT") return false;
throw err;
}
}
async function isManagedLegacyGeminiFile(filePath) {
try {
const content = await fs.readFile(filePath, "utf8");
return content.includes(MANAGED_MARKER);
} catch (err) {
if (err?.code === "ENOENT") return false;
throw err;
}
}
export async function cleanupLegacyGeminiAssets({
scope = "project",
homeDir = resolveAgestraHome(),
repoRoot = process.cwd(),
} = {}) {
const removed = [];
const skipped = [];
const legacyTargetPaths = [];
for (const relativePath of [...LEGACY_GEMINI_ASSET_PATHS].sort()) {
const filePath = geminiTargetPath({
asset: { relativePath },
scope,
homeDir,
repoRoot,
});
legacyTargetPaths.push(path.resolve(filePath));
if (await isManagedLegacyGeminiFile(filePath)) {
await fs.unlink(filePath);
removed.push(filePath);
for (const dirPath of cleanupDirsForTarget({ relativePath, filePath, scope, homeDir, repoRoot })) {
await removeEmptyDirectory(dirPath);
}
continue;
}
if (await exists(filePath)) skipped.push(filePath);
}
if (removed.length > 0) {
const removedPaths = new Set(removed.map((filePath) => path.resolve(filePath)));
const legacyPaths = new Set(legacyTargetPaths);
await pruneManifestTargets(homeDir, (target) =>
target.host === "gemini" &&
target.scope === scope &&
target.kind === "file" &&
(removedPaths.has(path.resolve(target.path)) || legacyPaths.has(path.resolve(target.path))));
}
return { removed, skipped };
}
function cleanupDirsForTarget({ relativePath, filePath, scope, homeDir, repoRoot }) {

@@ -296,2 +392,3 @@ if (relativePath === "GEMINI.md") {

const relativeFromCommands = path.relative(commandsRoot, filePath);
if (!isPublicGeminiCommand(relativeFromCommands)) continue;
const content = await expandCommandReferences(

@@ -314,2 +411,3 @@ await fs.readFile(filePath, "utf8"),

const skillName = normalizeSkillName(path.basename(filePath), content);
if (!PUBLIC_GEMINI_SKILLS.has(skillName)) continue;
assets.push({

@@ -412,2 +510,4 @@ relativePath: path.join(".gemini", "skills", skillName, "SKILL.md"),

await cleanupLegacyGeminiAssets({ scope, homeDir, repoRoot });
return installManagedFiles({

@@ -426,4 +526,5 @@ host: "gemini",

homeDir = resolveAgestraHome(),
repoRoot = process.cwd(),
}) {
return uninstallManagedFiles({
const result = await uninstallManagedFiles({
host: "gemini",

@@ -433,2 +534,4 @@ scope,

});
await cleanupLegacyGeminiAssets({ scope, homeDir, repoRoot });
return result;
}
+10
-0
scripts/host-assets/manifest.mjs

@@ -78,2 +78,12 @@ import fs from "node:fs/promises";

export async function pruneManifestTargets(homeDir, predicate) {
const manifest = await loadManifest(homeDir);
const targets = manifest.targets.filter((target) => !predicate(target));
if (targets.length === manifest.targets.length) return manifest;
manifest.targets = targets;
await saveOrRemoveManifest(homeDir, manifest);
return manifest;
}
async function saveManifest(homeDir, manifest) {

@@ -80,0 +90,0 @@ await writeJson(manifestPath(homeDir), normalizeManifest(manifest));

+15
-16
skills/leader.md

@@ -217,5 +217,6 @@ ---

2. Running its information-gathering phase (Clarity Gate, scope, focus areas, Mode A/B)
3. Capturing the domain's `조사 방식` / research topology gate when provider-backed
investigation is possible: Host-native first (`host-seeded`), `council`,
`provider-seeded`, or `automatic`
3. Capturing the domain's research viewpoint/lens. Renewed public `/agestra
research` and `/agestra review` use fixed host-owned research
(`research_topology: "host-seeded"`) and must not ask the user to choose a
research topology or provider investigation mode.
4. Building the handoff packet for `agestra:agestra-team-lead`

@@ -233,15 +234,13 @@ 5. Invoking team-lead with `Mode: multi-ai` pre-selected so team-lead does not re-interview

monitoring instead of stopping.
- Resolving the selected research topology into concrete host-native research
assignments, external provider assignments, seed-provider work, and debate
participants. If topology is missing and asking is allowed, team-lead asks one
concise topology question; if asking is blocked, team-lead must
stop and return that the mandatory topology choice is required.
- For Host-native first, team-lead must invoke the active host's
`agestra-research` / `agestra-debate` native agents before considering the
current host's external CLI provider. `claude-host` / `codex-host` /
`gemini-host` sampling support is optional and must not be confused with the
native-agent route.
- Consensus orchestration: `agent_research_start` when the selected topology
requires research-only preprocessing with workflow profile, prompt pack,
questionSet, evidencePolicy, research lenses, and investigator assignments;
- Resolving the fixed host-owned research route into concrete host-native
research assignments and debate participants. For renewed public research and
review packets, missing topology means fixed `host-seeded`; team-lead must not
re-ask.
- Team-lead must invoke the active host's `agestra-research` /
`agestra-debate` native agents before considering the current host's external
CLI provider. `claude-host` / `codex-host` / `gemini-host` sampling support is
optional and must not be confused with the native-agent route.
- Consensus orchestration: `agent_research_start` when research-only
preprocessing is needed with workflow profile, prompt pack, questionSet,
evidencePolicy, research lenses, and investigator assignments;
it writes `research_submissions.json`, `research_transcript.json`, and

@@ -248,0 +247,0 @@ `aggregation.json` and does not start debate. Start debate separately with

+86
-47
skills/provider-guide.md

@@ -50,5 +50,8 @@ ---

### Text Work (리뷰/QA/보안/설계/아이디어)
### Text Work (리서치/리뷰와 내부 관점)
Available via `/agestra review`, `/agestra qa`, `/agestra security`, `/agestra design`, `/agestra idea`:
Public user-facing entries are limited to `/agestra research`, `/agestra
review`, and `/agestra setup`. QA, security, idea, design, and planning are
internal viewpoints / workflow profiles selected inside research or review,
not separate public slash commands.

@@ -60,17 +63,17 @@ | Mode | Description | When to Use |

When providers are enabled, explicit Agestra/multi-AI/provider requests go to
the leader router first, then to the matching workflow skill. The workflow skill
still owns its workflow profile, questionSet, lenses, and cost gates before team-lead dispatches providers. Idea, design, review,
security, and explicit research workflows ask for `조사 방식` / research topology
when provider-backed investigation is possible: Host-native first, Council
Research, Provider-seeded Research, or Decide automatically. Host-native first
is recorded internally as `host-seeded`.
the leader router first, then to the matching public workflow skill. The workflow skill
still owns its workflow profile, questionSet, lenses, and cost gates before team-lead dispatches providers. Renewed public `/agestra research` and `/agestra review`
are host-owned and lens/viewpoint driven: they do not ask for the old
provider-investigation topology choice, and they pass fixed
`research_topology: "host-seeded"` when provider-backed debate will challenge
prepared host findings.
`/agestra qa` uses the same three-topology pattern as the other domains: it
asks for Council QA, Host-native first QA, or Provider-seeded QA as a
mandatory design selection gate. No-questions directives do not authorize a
silent default and there is no host-only fallback mode. When no providers
are configured, stop and direct the user to `/agestra setup` instead. Trust
registration remains a separate security approval gate and cannot be
inferred from no-questions instructions. E2E execution is host-owned and
gated by `package.json` `scripts.e2e` auto-detection.
The QA viewpoint is an internal profile, not a separate QA slash command. It gathers
host-owned evidence, runs Connection / Boundary Checks (API/consumer data
shape, route/link mapping, state transition completeness, command/result
consistency, and E2E artifact interpretation), and records PASS/FAIL-style
evidence for later review/debate. No-questions directives do not authorize a
silent default. Trust registration remains a separate security approval gate
and cannot be inferred from no-questions instructions. E2E execution is
host-owned and gated by `package.json` `scripts.e2e` auto-detection.

@@ -81,3 +84,4 @@ ### Code and Test Authoring

authoring. Use the current host to make code/test changes first, then run
`/agestra qa`, `/agestra review`, or `/agestra security` on the result.
`/agestra research` for a host-owned evidence set or `/agestra review` with
the appropriate QA, security, design, planning, or critique viewpoint.

@@ -103,17 +107,18 @@ ## Auto-Routing Guidelines

**Routing principle:** any work that involves external providers (Codex/Gemini/Ollama) or multi-AI coordination must enter through an active workflow skill (`/agestra review` / `qa` / `security` / `design` / `idea`) which selects the workflow profile, questionSet, lenses, and gates before delegating to the `agestra:agestra-team-lead` agent. Do NOT suggest `ai_chat`, `agent_debate_*`, `agent_cross_validate`, or `ai_compare` as direct user-facing tools — those are MCP tools that team-lead invokes internally. Suggest the corresponding workflow command instead.
**Routing principle:** any work that involves external providers (Codex/Gemini/Ollama) or multi-AI coordination must enter through an active public workflow skill (`/agestra research` or `/agestra review`) which selects the workflow profile, questionSet, lenses, and gates before delegating to the `agestra:agestra-team-lead` agent when provider debate is needed. Do NOT suggest `ai_chat`, `agent_debate_*`, `agent_cross_validate`, or `ai_compare` as direct user-facing tools — those are MCP tools that team-lead invokes internally. Suggest the corresponding public workflow command instead.
| Intent | Suggested entry point | When |
|---|---|---|
| Host-owned research | `/agestra research` | User wants investigation/evidence before debate; ask for idea, QA, or security viewpoint |
| Explicit review command | `/agestra review` | User invoked `/agestra review`, or asked for review with explicit multi-AI/provider wording |
| Second opinion, other perspectives | `/agestra review` (multi-AI mode auto-engaged when providers available) | User wants multiple AIs/providers or named providers to compare viewpoints |
| Explicit validation / verification command | `/agestra qa` | User invoked `/agestra qa`, or asked for verification with explicit multi-AI/provider wording |
| Explicit security audit command | `/agestra security` | User invoked `/agestra security`, or asked for security review with explicit multi-AI/provider wording |
| Code changes, refactoring, fixes | Current host first, then `/agestra qa` or `/agestra review` | Agestra no longer performs provider-backed implementation as a primary workflow |
| Mention a provider by name (Gemini, Codex, Ollama) | Matching active workflow command (`/agestra review` / `qa` / `security` / `design` / `idea`) — team-lead picks up the named providers from user wording | Provider names alone don't pick a workflow; ask "어느 작업?" if ambiguous |
| Explicit architecture/design command | `/agestra design` | User invoked `/agestra design`, or asked for design with explicit multi-AI/provider wording |
| Compare options, which is better | `/agestra design` (`workflow: design`) for design options, `/agestra idea` (`workflow: idea`) for product/feature options | Use Agestra only when the comparison is explicitly multi-AI/provider-backed or `/agestra ...` was invoked |
| Large refactoring, many files to change | Current host first, then `/agestra qa` or `/agestra review` | If the user wants multiple AI opinions, use Agestra to review/QA the resulting diff |
| About to commit, create PR, finalize work | `/agestra qa` | User invoked `/agestra qa`, or explicitly wants multi-AI/provider-backed QA |
| Workflow unclear ("여러 AI로 뭐 좀") | `agestra-leader` skill (catch-all router) | Skill asks the user to pick from 5 options (idea / design / review / QA / security) |
| Validation / verification | `/agestra research` with QA evidence set, or `/agestra review` with QA lens when provider debate is wanted | User asks whether implementation matches a plan/spec/progress note |
| Security audit | `/agestra research` with security evidence set, or `/agestra review` with security lens when provider debate is wanted | User asks for secrets/auth/file/network/dependency/privacy risk assessment |
| Code changes, refactoring, fixes | Current host first, then `/agestra review` | Agestra no longer performs provider-backed implementation as a primary workflow |
| Mention a provider by name (Gemini, Codex, Ollama) | `/agestra review` if opinions/debate are wanted; `/agestra research` remains host-owned | Provider names alone don't pick a workflow; ask whether they want research or review if ambiguous |
| Architecture/design/planning judgment | `/agestra review` with design/planning lens | Use Agestra only when the comparison is explicitly multi-AI/provider-backed or `/agestra ...` was invoked |
| Compare options, which is better | `/agestra review` with idea/design/planning lens | Use provider debate to challenge the host-prepared findings |
| Large refactoring, many files to change | Current host first, then `/agestra review` | If the user wants multiple AI opinions, use Agestra to review the resulting diff |
| About to commit, create PR, finalize work | `/agestra review` with QA lens | Provider-backed QA judgment is a review viewpoint in the renewed public surface |
| Workflow unclear ("여러 AI로 뭐 좀") | ask whether they want `/agestra research` or `/agestra review`, then ask viewpoint | Public workflow choices are research/review/setup only |

@@ -124,8 +129,15 @@ ### Commands and Agents

|---------|--------------------|---------|
| `/agestra research` | active host `agestra-research` + research lenses | Host-owned evidence collection with idea, QA, or security viewpoint |
| `/agestra review` | `agestra:agestra-team-lead` + review lenses | Critique/evaluation: code quality, UX, performance, maintainability; writes `docs/reports/review/` |
| `/agestra qa` | `agestra:agestra-team-lead` + QA lenses | Document-based PASS/FAIL verification with optional E2E; writes `docs/reports/qa/` |
| `/agestra security` | `agestra:agestra-team-lead` + security lenses | Dedicated security audit; writes `docs/reports/security/` |
| `/agestra idea` | `agestra:agestra-team-lead` + idea research lenses | Improvement discovery and competitive analysis |
| `/agestra design` | `agestra:agestra-team-lead` + design lenses | Pre-implementation architecture exploration |
| `/agestra setup` | setup workflow | Locale and provider selection |
Internal viewpoints / profiles:
| Viewpoint | Public entry | Purpose |
|----------|--------------|---------|
| QA evidence | `/agestra research` or `/agestra review` | Document-based PASS/FAIL evidence with optional E2E, host-owned runtime checks, and boundary analysis |
| Security evidence | `/agestra research` or `/agestra review` | Secrets/auth/file/network/dependency/privacy risk assessment |
| Idea exploration | `/agestra research` or `/agestra review` | Improvement discovery, prior art, and opportunity analysis |
| Design / planning | `/agestra review` | Architecture option critique, plan readiness, and trade-off review |
### Utility Skills

@@ -141,9 +153,18 @@

Commands and hook-triggered suggestions go through the leader/workflow-skill gate when providers are available. Commands are explicit entry points; hooks detect explicit Agestra/multi-AI/provider intent from natural language.
Commands and explicit Agestra/multi-AI/provider suggestions go through the
leader/workflow-skill gate when providers are available. Commands are explicit
entry points; hooks are no longer installed by Agestra.
### Hook-Triggered Flow
### Natural-Language Suggestion Flow
When the UserPromptSubmit hook injects multi-AI context (e.g. user mentioned an external provider or used multi-AI phrasing), route through the matched **workflow skill** (`agestra:design` / `idea` / `review` / `qa` / `security`), which selects the workflow profile, questionSet, lenses, and gates before handing off to `agestra:agestra-team-lead` with the multi-AI handoff packet. Team-lead owns evidence gathering, consensus, approval gates, and reporting.
When the user explicitly asks for Agestra/multi-AI/provider work, route through
the matched public **workflow skill** (`agestra:agestra-research` or
`agestra:agestra-review`). The workflow skill selects the viewpoint,
workflow profile, questionSet, lenses, and gates before handing off to
`agestra:agestra-team-lead` when provider debate is needed. Team-lead owns
evidence gathering, consensus, approval gates, and reporting.
If the user's wording is multi-AI but the workflow is unclear, route to the `agestra-leader` skill which asks the user to pick from 5 options (idea / design / review / QA / security) and forwards to the chosen workflow skill.
If the user's wording is multi-AI but the workflow is unclear, ask whether they
want host-owned research or provider-backed review, then ask for the relevant
viewpoint/lens.

@@ -174,3 +195,3 @@ If no config exists, suggest `/agestra setup` first.

Phase 1: Situation Assessment (team-lead — environment_check, providers, target docs/diff)
Phase 2: Evidence Plan (team-lead — choose lenses, scope, provider roles, research topology)
Phase 2: Evidence Plan (team-lead — choose lenses, scope, provider roles, fixed host-owned research route)
Phase 3: Host-Owned Evidence Collection (host + agestra-research — inspect files/docs/tests/runtime evidence)

@@ -189,7 +210,6 @@ Phase 4: Provider Cross-Check / Consensus (providers + agestra-debate when needed)

**Host-native first:**
- For review, design, idea, security, research, and QA evidence work, the
preferred default is Host-native first (`host-seeded`): the active host's
`agestra-research` agent prepares evidence and `agestra-debate` can join
consensus through a host-turn route.
**Host-owned research:**
- For public research/review work, the fixed default is host-owned research
(`host-seeded`): the active host's `agestra-research` agent prepares evidence
and `agestra-debate` can join consensus through a host-turn route.
- Do not substitute the current host's external CLI provider for the host-native

@@ -199,4 +219,5 @@ role. For example, Claude Code should use `agestra-research` /

agents before `codex-cli`.
- Use external CLI providers for independent Council/Provider-seeded
participants or explicitly requested provider perspectives.
- Use external CLI providers for review/debate perspectives after host-owned
evidence is prepared, or for explicitly internal maintenance packets that
opt into non-public provider investigation.

@@ -223,7 +244,25 @@ **Research/debate split:**

**QA domain:**
- `/agestra qa` verifies existing work without code changes. It first asks Council QA vs Host-native first QA vs Provider-seeded QA as a mandatory design selection gate, then auto-detects E2E coverage via `package.json` `scripts.e2e`, writes QA reports under `docs/reports/qa/`, collects host-owned evidence, and runs Connection / Boundary Checks (API/consumer data shape, route/link mapping, state transition completeness, command/result consistency, and E2E artifact interpretation). Council QA uses `agent_research_start` with the QA workflow profile; all QA topologies start debate through `agent_consensus_start` with host-approved `aggregation`, supplied `questionSet`, and `evidencePolicy`. Every QA claim carries an `evidenceType` of `"empirical"` / `"inferential"` / `"mixed"` so the renderer can flag empirical refutations of inferential claims. If no providers are configured, stop and direct the user to `/agestra setup`. QA-only mode does not modify product code and does not author persistent E2E test files. If persistent tests are missing, QA records the gap and recommended scenarios as findings for the current host to implement separately.
**QA viewpoint/profile:**
- QA verifies existing work without code changes. It auto-detects E2E coverage
via `package.json` `scripts.e2e`, collects host-owned evidence, and runs
Connection / Boundary Checks (API/consumer data shape, route/link mapping,
state transition completeness, command/result consistency, and E2E artifact
interpretation). The QA workflow profile uses `agent_research_start` for
host-owned research and starts debate through `agent_consensus_start` only
from host-approved `aggregation`, supplied `questionSet`, and
`evidencePolicy`. Every QA claim carries an `evidenceType` of `"empirical"` /
`"inferential"` / `"mixed"` so the renderer can flag empirical refutations
of inferential claims. If no providers are configured for debate, stop and
direct the user to `/agestra setup` or continue the QA evidence run as
host-owned research. QA-only mode does not modify product code and does not
author persistent E2E test files. If persistent tests are missing, QA records
the gap and recommended scenarios as findings for the current host to
implement separately.
**Security domain:**
- `/agestra security` writes a security report under `docs/reports/security/`. Tool installs, heavyweight static scans, networked package audits, and large-log scans require explicit user approval with the exact command, scope, privacy/telemetry note, expected time, and artifact path.
**Security viewpoint/profile:**
- Security-focused research/review writes security evidence or reports under
the selected workflow's report directory. Tool installs, heavyweight static
scans, networked package audits, and large-log scans require explicit user
approval with the exact command, scope, privacy/telemetry note, expected
time, and artifact path.

@@ -230,0 +269,0 @@ **QA failure handling:**

+7
-5
skills/references/lenses/README.md

@@ -13,2 +13,4 @@ # Agestra Lenses

- 렌즈가 충돌하면 더 구체적인 작업 계약을 우선한다.
- 공개 `/agestra research`는 호스트 소유 조사다. 외부 provider, 로컬 모델, CLI provider는 이 흐름에서 조사자가 아니다.
- 공개 `/agestra review`는 새 조사를 시작하지 않는다. 이미 있는 코드, 문서, diff, 또는 준비된 리서치 결과를 놓고 토론하고 검토한다.
- 조사와 토론의 기계 입력/출력은 JSON 계약을 따른다. Markdown은 사람이 읽는 보고서에 쓴다.

@@ -21,5 +23,5 @@ - `prompts/` 조각은 렌즈 원본이 아니다. 런타임 판단 기준은 이 폴더의 lens 문서와 에이전트 assignment에서 온다.

| --- | --- |
| `research-provider-rules.md` | 외부 provider 조사 prompt에 항상 들어가는 역할 경계, lens discipline, evidence 품질 기준 |
| `research-provider-rules.md` | 레거시/내부 provider 조사 경계 참고. 공개 `/agestra research`에는 provider 조사를 붙이지 않는다. |
| `research.md` | 공통 리서치 primitive, evidence surface, research run 조합 규칙 |
| `research-domains/*.md` | idea/design/review/QA/security 도메인별 조사 팩 |
| `research-domains/*.md` | idea/QA/security 중심 조사 팩. design/review/planning은 내부 또는 준비 자료용 렌즈 |
| `review.md` | 코드 품질, 사용자 불편, 유지보수성, 리소스, 레거시, 하드코딩 검토 |

@@ -33,3 +35,3 @@ | `qa.md` | 문서-구현 대조, 진행표 진실성, 승인 없는 MVP/타협 감지 |

`skills/*.md`는 워크플로 진입점이다. 사용자가 `/agestra qa`나 `/agestra review` 같은 흐름을 시작하면 어떤 질문을 하고 어떤 도구를 호출할지 정한다.
`skills/*.md`는 워크플로 진입점이다. 사용자가 `/agestra research`나 `/agestra review` 같은 흐름을 시작하면 어떤 질문을 하고 어떤 도구를 호출할지 정한다.

@@ -40,3 +42,3 @@ `skills/references/lenses/*.md`는 그 워크플로 안에서 필요한 순간에 펼쳐 보는 기준표다. 스킬 문서에 모든 세부 체크리스트를 복사하지 않는다. 스킬은 "어떤 렌즈를 읽어야 하는지"를 가리키고, 렌즈는 "무엇을 중심으로 볼지"를 설명한다.

리서치 에이전트 정의는 하나로 유지한다. 대신 실제 조사는 여러 research run으로 나눌 수 있다.
리서치 에이전트 정의는 하나로 유지한다. 대신 실제 조사는 호스트가 여러 research run으로 나눌 수 있다.

@@ -52,2 +54,2 @@ 예:

팀리더 또는 research aggregator가 여러 run 결과를 취합한다.
호스트 또는 research aggregator가 여러 run 결과를 취합한다. provider 토론이 필요하면 먼저 리서치를 끝내고, 그 결과 문서나 기존 코드/문서를 `/agestra review`의 입력으로 넘긴다.
+92
-314
skills/research.md
---
name: agestra-research
description: >
Use only inside an active Agestra workflow, an explicit `/agestra research` command,
or explicit multi-AI/provider research planning. Handles investigation topology,
competitor or evidence collection, and structured research artifacts when Agestra
is already selected. Trigger examples include: "/agestra research",
"multi-AI research plan", "provider research plan", "Codex and Gemini research",
"조사 방식", "여러 AI로 조사", "Council Research", "Host-native first",
"Provider-seeded Research", "provider evidence packet".
Plain research requests without `/agestra` or explicit multi-AI/provider wording stay
with the current host; they are not Agestra natural-language auto-triggers.
Use only inside an active Agestra workflow, an explicit `/agestra research`
command, or explicit host-owned Agestra research planning. It collects
evidence with idea, QA, or security viewpoints and writes durable research
artifacts. Plain research requests without `/agestra` or explicit
multi-AI/provider wording stay with the current host.
---

@@ -17,62 +13,52 @@

Run research as an explicit workflow, not as a hidden team-lead subroutine.
The skill requires a domain, chooses or proposes a 조사 방식, creates a plan,
then produces Markdown and JSON artifacts.
Run host-owned research as an explicit workflow. The public research workflow is
viewpoint/lens driven, not provider-topology driven.
Plain research/investigation requests without `/agestra` or explicit multi-AI/provider
wording stay with the current host. Enter this skill only after the user selects
Agestra research explicitly or asks for provider-backed research.
Do not ask the user to choose a research topology or provider investigation
mode. Those old mode choices are not public renewal workflow inputs. External
providers do not investigate in this skill; they can challenge completed
research later through `/agestra review`.
## Required terms
## Required Terms
Use "조사 방식" for user-facing topology language.
Use "관점" for the public research viewpoint question.
Supported 조사 방식:
Supported viewpoints:
- Council Research
- Host-native first (recorded internally as `host-seeded`)
- Provider-seeded Research
- Idea exploration (`targetDomain: "idea"`)
- QA evidence set (`targetDomain: "qa"`)
- Security evidence set (`targetDomain: "security"`)
Provider-facing prompts are English. User-facing reports follow the configured locale.
External provider research prompts must include `skills/references/lenses/research-provider-rules.md`.
JSON keys, enum values, and artifact names stay English.
Provider-facing prompts are English. User-facing reports follow the configured
locale. JSON keys, enum values, and artifact names stay English.
## Research target domain gate
## Workflow
The research target domain is mandatory. Valid target domains:
### Phase 0: Setup State
- `idea`
- `design`
- `review`
- `qa`
- `security`
- `research`
Call `setup_status`. If setup is missing, run setup first and resume. Setup
locale determines the final Markdown report and user-visible summaries.
Do not infer or default the research target domain. If missing, ask one concise question.
Provider availability is not a gate for this skill. Do not stop because no
external provider is configured.
Canonical host research/debate boundary:
### Phase 1: Research Viewpoint
```text
호스트가 조사한다.
호스트가 정리한다.
시스템이 토론한다.
호스트가 문서화한다.
```
If the request does not already state one of the supported viewpoints, ask one
concise question with these choices:
Standalone `/agestra research` produces research artifacts and a human report; it does not create a bundled participant for a later domain debate. When research should continue into idea/design/review/security/qa consensus, hand off to team-lead to call `agent_research_start` for the target workflow, inspect `aggregation.json`, then start debate separately with `agent_consensus_start`. External AI research and debate run in separate fresh sessions, even when the same provider participates in both phases.
| Option | Description |
| --- | --- |
| **Idea exploration** | Find product/project ideas, improvement candidates, prior art, user pain, or opportunity evidence. |
| **QA evidence set** | Gather evidence for whether implementation matches a plan, spec, progress note, or expected behavior. |
| **Security evidence set** | Gather trust-boundary, secret, auth, file/command/network, dependency, privacy, or hardening evidence. |
## Workflow
Do not ask for a research topology or provider investigation mode.
### Phase 0: Setup and provider state
### Phase 2: Research Brief
Call `setup_status`. If setup is missing, run setup first and resume.
Then call `environment_check` and `provider_list`.
### Phase 1: Research brief
Collect only missing fields:
- research target domain
- topic/question
- target files, docs, or sources
- target files, docs, sources, workspace, or app surface
- freshness/current-information requirement

@@ -82,57 +68,48 @@ - constraints and exclusions

### Phase 2: 조사 방식 selection
Load the common research lens plus the selected domain pack:
Recommend or confirm one 조사 방식:
- `skills/references/lenses/research.md`
- `skills/references/lenses/research-domains/idea.md`
- `skills/references/lenses/research-domains/qa.md`
- `skills/references/lenses/research-domains/security.md`
- Council Research: host and external providers independently investigate with distinct lenses, then cross-review and debate.
- Host-native first: the active host's native `agestra-research` agent creates and persists the first seed/source document, then external participants challenge it through the supplied research workflow profile and question set. Record internally as `host-seeded`.
- Provider-seeded Research: the selected seed provider creates the first seed/evidence artifact, then host/reviewer participants challenge it independently.
Use the domain pack as the question guide and lens/rubric source.
This is a mandatory design selection gate. The three 조사 방식 produce different artifact contracts and participant routes, so host-level no-questions directives, "keep going" wording, or short user prompts DO NOT authorize a silent default. Always present the three options through `AskUserQuestion` (or the host equivalent), each with a one-line description, and wait for the user's explicit choice before any provider fan-out.
### Phase 3: Host Research Plan
If no external providers are available, stop Agestra orchestration and tell the user to run setup or handle the research directly outside Agestra.
Create a concise assignment table for host-native research. Each row should
include `item_id`, `domain`, `lens`, `question`, `scope`, `deliverable`,
`expected_artifact`, and optional `rationale`.
For Council Research, first create a table of workflow-profile investigation items and participant assignments, then ask the user to approve or modify it.
Each assignment row must make the runtime contract explicit: `item_id`, `assignee`, `domain`, `role`, `lens`, `question`, `deliverable`, `priority`, `expected_artifact`, and optional `rationale`.
Provider fan-out is forbidden until that plan is approved or modified by the user.
Split broad work into focused `agestra-research` runs. The same agent definition
may be run multiple times with different lenses.
Native researcher/helper agents are host-owned. External providers in the assignment table participate through MCP, CLI, or chat routes and must not be described as creating or managing Claude/Codex/Gemini native agents.
Do not create a bundled research pseudo-participant, and do not carry research bundles through legacy source-document fields.
Canonical flow:
For Host-native first (`host-seeded`), the active host creates the host seed before provider fan-out:
```text
호스트가 조사한다.
호스트가 정리한다.
호스트가 문서화한다.
```
- Write the seed through the active host's native `agestra-research` agent as host-owned aggregation evidence and normalize it into `aggregation.items`.
- Do not pass the seed through legacy source-document fields.
- Include only explicit consensus participants in `participants`.
- Include at least one external reviewer participant outside the seed provider.
- Use `artifact_only_diagnostic: true` only when the user explicitly asks for host-only artifact capture; that path is not multi-AI consensus.
- Route any host debate participant to `agestra-debate` with `participant_routes`; do not substitute the current host's external CLI provider for this native role.
There is no provider fan-out phase in this skill.
For Provider-seeded Research:
### Phase 4: Research Execution
- Choose one configured, enabled, available `seed_provider`.
- Include the seed provider in `participants` with at least one independent reviewer participant.
- Pass `reviewer_participants` when the reviewer set should be explicit.
- Pass `seed_scope` when the seed artifact needs a focused brief.
- Pass `tool_broker_policy` as `none`, `host-brokered-readonly`, or `host-brokered-evidence`; this records explicit host-brokered expectations and does not give providers direct host tool-use.
- Do not describe reviewers as subordinate to the seed provider, and do not let the seed provider command other providers.
Native researcher/helper agents are host-owned. Use the active host's native
`agestra-research` agent for focused evidence collection when available.
External providers, local models, and external CLI providers are not canonical
research investigators in this workflow.
### Phase 3: Prompt stack and contracts
When using the MCP runner, call `agent_research_start` with host-native
investigator assignments only:
Use prompt stack parts in this order:
- `workflow`: `idea`, `qa`, or `security`
- `target`: brief target/question
- `researchLenses`: selected lens names
- `investigators`: `agestra-research` assignment rows
- `promptPack`: common research guide, selected domain pack, and
`ResearchSubmission` output contract
- `files`: bounded read-only context when relevant
1. external provider research rules
2. common research guide
3. target-domain research card
4. output contract
5. assignment lens / scope / deliverable task packet
JSON enforcement belongs to the output contract.
Common provider rules only cover evidence, assumptions, opinions, and disagreement preservation.
Do not send the full `agestra-research` agent or skill document to providers.
### Phase 4: Artifacts
For Council Research, the approved MCP packet must call `agent_research_start` first and produce an `agent_consensus_start` packet only after host preprocessing has prepared `aggregation.items`:
`agent_research_start` is research-only. It receives the workflow profile,

@@ -142,226 +119,23 @@ prompt pack, `questionSet`, `evidencePolicy`, research lenses, and investigator

`research_transcript.json`, and `aggregation.json`. It does not start debate.
debate-only `agent_consensus_start` runs from prepared `aggregation`, supplied
`questionSet`, and `evidencePolicy`; `workflow` is a report/artifact label only,
not a debate routing branch.
```json
{
"workflow": "research",
"participants": ["<explicit-consensus-participant>"],
"questionSet": {
"id": "research.findings-and-sources",
"title": "Research findings and sources validation",
"requiredQuestions": [
{
"id": "claim",
"prompt": "Is the research claim specific and answerable?",
"verdictField": "claimVerdict",
"allowedVerdicts": ["yes", "no", "unclear"],
"required": true
},
{
"id": "source",
"prompt": "Is the claim supported by traceable source evidence?",
"verdictField": "sourceVerdict",
"allowedVerdicts": ["yes", "no", "partial", "unclear"],
"required": true
},
{
"id": "conflict",
"prompt": "Are conflicting sources or uncertainties preserved?",
"verdictField": "conflictVerdict",
"allowedVerdicts": ["yes", "no", "not-applicable", "unclear"],
"required": true
},
{
"id": "action",
"prompt": "What follow-up or decision does this finding support?",
"verdictField": "actionVerdict",
"allowedVerdicts": ["decision-ready", "needs-followup", "background-only", "rejected"],
"required": true
},
{
"id": "status",
"prompt": "Should this be accepted, followed up, background context, or rejected?",
"verdictField": "finalStatus",
"allowedVerdicts": ["accepted", "needs_followup", "background", "rejected"],
"required": true
}
],
"finalStatus": {
"field": "finalStatus",
"allowedValues": ["accepted", "needs_followup", "background", "rejected"]
}
},
"aggregation": { "aggregationId": "<approved aggregation id>", "items": [] },
"evidencePolicy": { "preserveItemEvidenceType": true, "preserveStanceEvidenceType": true },
"participant_routes": []
}
```
If the host performs the research directly, call `agent_research_record` after
the Markdown report body exists. Include the target domain, research plan,
assignment table, claims with evidence refs, validation status, Markdown report
path/body, and the reason provider fan-out was not invoked.
For Host-native first (`host-seeded`), the MCP packet must include:
Expected supporting artifacts:
```json
{
"workflow": "research",
"participants": ["host-seed", "<external-reviewer>"],
"questionSet": {
"id": "research.findings-and-sources",
"title": "Research findings and sources validation",
"requiredQuestions": [
{
"id": "claim",
"prompt": "Is the research claim specific and answerable?",
"verdictField": "claimVerdict",
"allowedVerdicts": ["yes", "no", "unclear"],
"required": true
},
{
"id": "source",
"prompt": "Is the claim supported by traceable source evidence?",
"verdictField": "sourceVerdict",
"allowedVerdicts": ["yes", "no", "partial", "unclear"],
"required": true
},
{
"id": "conflict",
"prompt": "Are conflicting sources or uncertainties preserved?",
"verdictField": "conflictVerdict",
"allowedVerdicts": ["yes", "no", "not-applicable", "unclear"],
"required": true
},
{
"id": "action",
"prompt": "What follow-up or decision does this finding support?",
"verdictField": "actionVerdict",
"allowedVerdicts": ["decision-ready", "needs-followup", "background-only", "rejected"],
"required": true
},
{
"id": "status",
"prompt": "Should this be accepted, followed up, background context, or rejected?",
"verdictField": "finalStatus",
"allowedVerdicts": ["accepted", "needs_followup", "background", "rejected"],
"required": true
}
],
"finalStatus": {
"field": "finalStatus",
"allowedValues": ["accepted", "needs_followup", "background", "rejected"]
}
},
"aggregation": {
"aggregationId": "<host seed aggregation id>",
"items": [
{
"id": "HOST-SEED",
"title": "<claim>",
"claim": "<what external reviewers should challenge>",
"evidenceType": "empirical"
}
]
},
"evidencePolicy": { "preserveItemEvidenceType": true, "preserveStanceEvidenceType": true }
}
```
For Provider-seeded Research, the MCP packet must include:
```json
{
"workflow": "research",
"participants": ["<configured-seed-provider>", "<reviewer-provider-or-host-participant>"],
"questionSet": {
"id": "research.findings-and-sources",
"title": "Research findings and sources validation",
"requiredQuestions": [
{
"id": "claim",
"prompt": "Is the research claim specific and answerable?",
"verdictField": "claimVerdict",
"allowedVerdicts": ["yes", "no", "unclear"],
"required": true
},
{
"id": "source",
"prompt": "Is the claim supported by traceable source evidence?",
"verdictField": "sourceVerdict",
"allowedVerdicts": ["yes", "no", "partial", "unclear"],
"required": true
},
{
"id": "conflict",
"prompt": "Are conflicting sources or uncertainties preserved?",
"verdictField": "conflictVerdict",
"allowedVerdicts": ["yes", "no", "not-applicable", "unclear"],
"required": true
},
{
"id": "action",
"prompt": "What follow-up or decision does this finding support?",
"verdictField": "actionVerdict",
"allowedVerdicts": ["decision-ready", "needs-followup", "background-only", "rejected"],
"required": true
},
{
"id": "status",
"prompt": "Should this be accepted, followed up, background context, or rejected?",
"verdictField": "finalStatus",
"allowedVerdicts": ["accepted", "needs_followup", "background", "rejected"],
"required": true
}
],
"finalStatus": {
"field": "finalStatus",
"allowedValues": ["accepted", "needs_followup", "background", "rejected"]
}
},
"aggregation": {
"aggregationId": "<provider seed aggregation id>",
"items": [
{
"id": "PROVIDER-SEED",
"title": "<seed claim>",
"claim": "<what reviewers should challenge>",
"evidenceType": "inferential"
}
]
},
"evidencePolicy": { "preserveItemEvidenceType": true, "preserveStanceEvidenceType": true }
}
```
If a seed artifact already exists, convert its supported claims into `aggregation.items` before starting consensus.
Progress contract: surface concise phase updates every 30-60 seconds during
provider, host-participant, or debate phases. Poll `agent_debate_status`,
`run_observable_events` with a cursor when available.
If trace is `cold-start`, report the current local phase and keep monitoring
instead of stopping.
Expected JSON artifacts:
- `research_submissions.json`
- `research_transcript.json`
- `aggregation.json`
- `debate_transcript.json`
- `workflow_result.json`
- `artifact_index.json` when the host needs an index
- `run_report.json`, `gate_ledger.json`, `research_plan.json`,
`assignment_table.json`, `individual_results.json`, `evidence_packet.json`,
`validated_findings.json`, `dispute_ledger.json`, and
`consensus_ledger.json` as legacy/internal supporting artifacts when the
workflow records that detail
- `run_report.json`
- `gate_ledger.json`
- `evidence_packet.json`
- `artifact_index.json`
The document flow is a threaded aggregation document plus a concise final decision document. Markdown report should summarize agreed conclusions, unique insights, disputed items, and rejected or dismissed claims separately.
Markdown reports should include an `실행 증거` section that links only to run evidence artifact paths, not prompt bodies or prompt capsule summary tables.
The document flow is a threaded aggregation document plus a concise final decision document when enough evidence exists to synthesize decisions.
For host-owned investigation material that feeds provider-backed research, call `agent_research_record` after the host report body exists. This records `run_report.json`, `gate_ledger.json`, `evidence_packet.json`, `artifact_index.json`, the evidence routing reason, and the optional Markdown report.
`agent_research_record` is only a host-owned evidence recording helper. It does
not replace `agent_research_start`, `aggregation.json`, or the separate
`agent_consensus_start` debate flow.
### Phase 5: Validation
Use finding-validator when claims require confirmation:
Use finding validation when claims require confirmation:

@@ -371,5 +145,6 @@ - split claims

- check files/docs/tests/callers/framework behavior when available
- classify as `confirmed`, `dismissed`, or `needs_human_review`
- classify as `validated`, `dismissed`, or `needs_human_review`
Do not let finding-validator become another reviewer; it validates claims already proposed by reviewers, QA, security, design, or research participants.
Do not let validation become another reviewer; it checks claims already produced
by research.

@@ -380,8 +155,11 @@ ## Completion

- domain is recorded
- 조사 방식 is recorded
- assignment table exists when Council Research is used
- `seed_provider` is recorded when Provider-seeded Research is used
- viewpoint and target domain are recorded
- research brief is recorded
- host assignment table exists or direct-host reason is recorded
- JSON artifacts are written or explicitly marked not applicable
- Markdown report is written
- validation evidence is recorded for checked findings
- Markdown report is written unless chat-only output was requested
- validation evidence is recorded for checked claims
Surface the result in the user's language with report paths, agreed findings,
weak findings, dismissed claims, unknowns, and a suggested `/agestra review`
viewpoint when provider debate would help.
+20
-18
skills/review.md

@@ -15,3 +15,4 @@ ---

Use `/agestra qa` for document-based acceptance verification. Use `/agestra security` for deep security review.
For document-based acceptance or security-focused judgment, keep the public
entry point as `/agestra review` and select the QA or security viewpoint/lens.

@@ -66,3 +67,4 @@ Review writes a durable report under `docs/reports/review/` unless the user explicitly asks for chat-only output.

Do not treat "Basic safety smells" as a full security audit. If the user wants security, route to `/agestra security`.
Do not treat "Basic safety smells" as a full security audit. If the user wants
security, keep this workflow and record a security-focused review lens.

@@ -82,16 +84,14 @@ Ask depth when useful:

Also ask selected research inputs before provider fan-out:
- "Provider-backed review can use Host-native first, Council, or Provider-seeded research. What should the selected investigation look for: regression-prone areas, blast radius / downstream callers, prior incidents, dependency / supply-chain concerns, current-information needs, or skip?"
- "Should any participant or lens receive a specific research assignment, or should team-lead choose the assignment rows?"
- "What should host-owned review research look for: regression-prone areas, blast radius / downstream callers, prior incidents, dependency / supply-chain concerns, current-information needs, or skip?"
- "Should any review lens receive a specific host-owned research assignment, or should team-lead choose the assignment rows?"
### Phase 3: Choose 조사 방식
### Phase 3: Record host-owned research route
Before provider fan-out, ask once which investigation topology to use unless the user already specified it:
Do not ask the user to choose a research topology or provider investigation mode for `/agestra review`. Review uses host-owned research by default:
| Option | Description |
|--------|-------------|
| **Host-native first (Recommended)** | The active host's native `agestra-research` agent prepares bounded review evidence first; providers challenge and debate the prepared findings. Record internally as `host-seeded`. |
| **Council Research** | Host and providers independently inspect assigned review lenses before consolidation and debate. |
| **Provider-seeded Research** | One selected provider creates the first review seed/evidence artifact; host and other providers challenge it. |
- `research_topology: "host-seeded"`
- `조사 방식: "host-owned"`
- `allow_external_research_investigators: false`
This is a mandatory design selection gate. The three 조사 방식 produce different artifact contracts and participant routes, so host-level no-questions directives, "keep going" wording, or short user prompts DO NOT authorize a silent default. Always present the three options through `AskUserQuestion` (or the host equivalent), each with a one-line description, and wait for the user's explicit choice before any provider fan-out. If Provider-seeded Research is selected and the seed provider is not explicit, record the seed provider as pending; after provider availability is listed, ask which available provider should seed. Do not infer it.
The selected review lenses and research notes drive the active host's `agestra-research` assignments. External providers may challenge and debate prepared host-owned findings, but they are not research investigators unless an internal/legacy handoff explicitly opts into that behavior outside this public skill.

@@ -108,3 +108,3 @@ ### Phase 4: Route execution

**Provider-backed path — 1+ external providers available (multi-AI):**
Hand off to the `agestra:agestra-team-lead` agent with multi-AI mode **pre-selected**. Provider-backed review uses the selected research topology flow:
Hand off to the `agestra:agestra-team-lead` agent with multi-AI mode **pre-selected** and review research topology **pre-selected**. Provider-backed review uses the fixed host-owned research flow:

@@ -128,6 +128,8 @@ ```text

- **Workflow profile:** review profile with `workflow: "review"`, review `questionSet`, prompt pack, and `evidencePolicy`
- **Research topology / 조사 방식:** {selected in Phase 3 — `host-seeded`, `council`, `provider-seeded`, or `automatic`}; seed or research findings become `aggregation.items`
- **Host-native route:** for Host-native first (`host-seeded`), run active-host `agestra-research` before external provider fan-out; route any host debate participant to `agestra-debate` with `participant_routes`; do not substitute the current host's external CLI provider for this native role
- **Research topology / 조사 방식:** fixed internal `host-seeded` (`host-owned`); team-lead must NOT re-ask for topology; host research findings become `aggregation.items`
- **Host-native route:** run active-host `agestra-research` before external provider challenge/debate; route any host debate participant to `agestra-debate` with `participant_routes`; do not substitute the current host's external CLI provider for this native role
- **Research lenses:** selected review lenses and optional assignment rows that shape host-owned `agestra-research` work
- **Research notes:** {what the selected investigation should look for — regression-prone areas, blast radius, prior incidents, dependency concerns, current-information needs}
- **Research assignments:** {optional participant/lens rows for `research_assignments`, or "team-lead choose"}
- **Research assignments:** {optional host-owned lens rows for `research_assignments`, or "team-lead choose"}
- **External research investigators:** `allow_external_research_investigators: false`
- **Available providers:** {from environment_check, exclude `ollama` unless explicitly requested for lightweight commentary}

@@ -142,3 +144,3 @@ - **Requested providers:** {explicit names captured from the user's wording, e.g. `[codex, gemini]`; otherwise "all available review-capable"}

- Building the participant team (host reviewer + external providers)
- Resolving the selected research topology, then calling `agent_research_start` when investigation fan-out is required; call debate-only `agent_consensus_start` only after `aggregation.json` has been inspected and approved.
- Honoring the fixed `host-seeded` research topology without re-asking, then calling `agent_research_start` for host-owned investigation; call debate-only `agent_consensus_start` only after `aggregation.json` has been inspected and approved.
- Ensuring external AI research and debate use separate fresh sessions.

@@ -179,3 +181,3 @@ - Never creating a bundled research pseudo-participant and never carrying research bundles through legacy source-document fields.

- Review verdict
- Whether `/agestra qa` or `/agestra security` should be run next
- Whether another `/agestra review` pass with a QA, security, idea, design, or planning viewpoint should be run next

@@ -182,0 +184,0 @@ ## Constraints

+26
-15
skills/setup.md

@@ -13,5 +13,5 @@ ---

### Step 1: Detect installed CLIs
### Step 1: Detect installed providers
Call `environment_check` and `setup_status` to detect which AI CLIs are installed on the system and whether host-native assets are current.
Call `environment_check` and `setup_status` to detect which AI CLIs or local AI servers are available on the system and whether host-native assets are current.

@@ -28,4 +28,15 @@ If the current host is Codex, call `host_assets_status` for user scope and project scope when available. `setup_status` and `host_assets_status` are status-only checks. This setup skill must not call `host_assets_install`.

### Step 2: Ask user which AIs to use
### Step 2: Ask language
Ask which language to use for Agestra moderator/setup text:
- 한국어 → `ko`
- English → `en`
- 日本語 → `ja`
- 中文 → `zh`
Use `AskUserQuestion` when available, or a plain numbered prompt as fallback. Wait for an explicit language choice before writing config.
### Step 3: Ask user which AIs to use
Based on detection results, present ONLY the installed/available AIs as choices.

@@ -42,14 +53,13 @@ Use `AskUserQuestion` with multi-select when available, or a plain numbered prompt with comma/list selection as fallback. Use the user's language for the question. Wait for an explicit provider selection; do not infer enabled providers from installation alone.

☐ Ollama (localhost:11434)
☐ LM Studio (localhost:1234)
```
Also ask which language to use for Agestra moderator/setup text:
If the selected providers include `ollama` or `lm-studio`, ask one follow-up local AI role question:
- 한국어 → `ko`
- English → `en`
- 日本語 → `ja`
- 中文 → `zh`
- Advisory → `advisory` (recommended; transcript only, excluded from default consensus)
- Full debater → `full_debater` (formal debate participant after readiness and format checks)
Use `AskUserQuestion` when available, or a plain numbered prompt as fallback. Wait for an explicit language choice before writing config.
If no local AI provider is selected, do not ask this question; unselected local AI providers are stored as disabled.
### Step 3: Generate providers.config.json
### Step 4: Generate providers.config.json

@@ -89,2 +99,4 @@ Based on user selection, generate the config file directly:

- `locale`: `ko`, `en`, `ja`, or `zh`
- Selected local AI providers store `config.localAiRole` as `advisory` or
`full_debater`; unselected local AI providers store `disabled`
- Prefer calling `setup_apply`; it writes to `AGESTRA_CONFIG_PATH` when set,

@@ -94,3 +106,3 @@ otherwise the shared `~/.agestra/providers.config.json`. Existing legacy

### Step 4: Confirm and proceed
### Step 5: Confirm and proceed

@@ -116,9 +128,8 @@ After config is saved, confirm to user:

When user triggers review/idea/design (via hook or command):
When user triggers research/review:
- Use the existing provider config instead of asking provider setup again
- Still run the matching workflow skill's question sheet and selected workflow
profile, including workflow-specific cost gates, prompt pack, questionSet,
evidencePolicy, lenses, and `조사 방식` / research topology selection when
provider-backed research is possible
profile, including workflow-specific prompt pack, questionSet, evidencePolicy,
and lenses. Do not ask for public research topology choices.
- Route through team-lead for consensus/debate using the enabled providers
- If only 1 provider is enabled, inform user that debate needs 2+ participants and offer to add Claude as participant
-16
.gemini/commands/agestra/design.toml
# Generated by Agestra. Managed file.
description = "Explore architecture and design trade-offs before implementation"
prompt = """
You are executing the `/agestra design` Gemini command.
- Start with `setup_status`, then `environment_check` and `provider_list`.
- For investigation-including workflows, route through `agent_research_start`, then start debate separately with `agent_consensus_start`.
- Host research/debate contract uses workflow profiles, `aggregation`, `questionSet`, and `evidencePolicy`:
호스트가 조사한다.
호스트가 정리한다.
시스템이 토론한다.
호스트가 문서화한다.
- External AI research and debate run in separate fresh sessions, even when the same provider participates in both phases.
@{commands/design.md}
"""
-16
.gemini/commands/agestra/idea.toml
# Generated by Agestra. Managed file.
description = "Discover and refine ideas with Agestra"
prompt = """
You are executing the `/agestra idea` Gemini command.
- Start with `setup_status`, then `environment_check` and `provider_list`.
- For investigation-including workflows, route through `agent_research_start`, then start debate separately with `agent_consensus_start`.
- Host research/debate contract uses workflow profiles, `aggregation`, `questionSet`, and `evidencePolicy`:
호스트가 조사한다.
호스트가 정리한다.
시스템이 토론한다.
호스트가 문서화한다.
- External AI research and debate run in separate fresh sessions, even when the same provider participates in both phases.
@{commands/idea.md}
"""
-16
.gemini/commands/agestra/qa.toml
# Generated by Agestra. Managed file.
description = "Run document-first QA with Agestra"
prompt = """
You are executing the `/agestra qa` Gemini command.
- Start with `setup_status`, then `environment_check` and `provider_list`.
- For investigation-including workflows, route through `agent_research_start`, then start debate separately with `agent_consensus_start`.
- Host research/debate contract uses workflow profiles, `aggregation`, `questionSet`, and `evidencePolicy`:
호스트가 조사한다.
호스트가 정리한다.
시스템이 토론한다.
호스트가 문서화한다.
- External AI research and debate run in separate fresh sessions, even when the same provider participates in both phases.
@{commands/qa.md}
"""
-16
.gemini/commands/agestra/security.toml
# Generated by Agestra. Managed file.
description = "Run a security review with Agestra"
prompt = """
You are executing the `/agestra security` Gemini command.
- Start with `setup_status`, then `environment_check` and `provider_list`.
- For investigation-including workflows, route through `agent_research_start`, then start debate separately with `agent_consensus_start`.
- Host research/debate contract uses workflow profiles, `aggregation`, `questionSet`, and `evidencePolicy`:
호스트가 조사한다.
호스트가 정리한다.
시스템이 토론한다.
호스트가 문서화한다.
- External AI research and debate run in separate fresh sessions, even when the same provider participates in both phases.
@{commands/security.md}
"""
-158
commands/design.md
---
description: "Explore architecture and design trade-offs before implementation"
argument-hint: "[idea, feature, or system to design]"
---
You are executing the `/agestra design` command.
**Subject:** $ARGUMENTS
Plain review/QA/check requests without `/agestra` or explicit multi-AI/provider wording stay with the current host; they are not Agestra natural-language auto-triggers.
Agestra natural-language routing requires explicit Agestra/multi-AI/provider wording such as "Agestra", "아제스트라", "multiple AIs", "all AIs", "other AI", "multi-AI", "Codex and Gemini", "provider comparison", or "프로바이더 비교". Explicit `/agestra ...` commands remain supported.
Host interaction fallback: when this workflow says `AskUserQuestion`, use a structured question UI if the current host exposes one. If it is unavailable (for example, in Codex), ask the same question plainly in chat, present the same options, and wait for the user's answer.
## Step 0: Setup preflight (MANDATORY)
Before anything else, call `setup_status`. If it reports `Setup required: yes` or `Current config: not found`, **automatically enter the interactive setup flow before continuing**:
1. Invoke the `agestra:setup` skill (or run `/agestra setup` inline) — provider detection, selection, locale, `setup_apply`.
2. After the config is written, resume this `/agestra design` command **from Step 1**, preserving `$ARGUMENTS`. Do not ask the user to retype.
Agestra uses a single shared `providers.config.json` resolved through `AGESTRA_CONFIG_PATH` or `~/.agestra/providers.config.json` (existing legacy `$CLAUDE_PLUGIN_ROOT/providers.config.json` remains readable). No config -> no sanctioned provider set or locale -> interactive setup is the only correct starting point. Auto-detect without explicit setup can silently include disabled providers. Do not silently choose defaults or write config without the user's provider/language choices.
Before any provider fan-out, run the shared workspace trust preflight for the exact current project root. If supported providers are blocked, ask once whether to register only this project folder. This is a security approval gate, not a clarifying question; "keep going" / no-questions instructions are not approval. After approval, call `provider_trust_apply` once per blocked provider. Use `provider_trust_apply_all` only when the host permission model explicitly allows batch trust changes. If approval cannot be obtained, skip blocked providers.
## Step 1: Determine design subject
If `$ARGUMENTS` is empty, present a starting-point choice using AskUserQuestion (in the user's language), or a plain numbered prompt if structured choices are unavailable:
| Option | Description |
|--------|-------------|
| **Describe an idea** | User has a specific feature or system in mind — proceed to designer |
| **Find ideas first** | User doesn't know what to design yet — run `/agestra idea` to discover opportunities, then return here |
| **Use saved idea** | Choose from project-facing idea records under `docs/ideas/` |
| **Use recent context** | Organize ideas from the current conversation into a design subject |
- If **"Describe an idea"**: ask a follow-up "What would you like to design?" and proceed.
- If **"Find ideas first"**: run `/agestra idea` to generate suggestions through the research and debate flow. After the user selects an idea from the results, save the idea decision under `docs/ideas/`, then continue to Step 2 with that as the subject.
- If **"Use saved idea"**: list relevant Markdown files under `docs/ideas/`, summarize the titles briefly, and ask which one to design using `AskUserQuestion` when available, or a plain numbered prompt as fallback. Do not infer the saved-idea selection.
- If **"Use recent context"**: scan the current conversation for previously discussed ideas, improvements, or features. Summarize them and ask the user which to design using `AskUserQuestion` when available, or a plain numbered prompt as fallback. Do not infer the context selection.
If `$ARGUMENTS` is provided, use it directly as the subject. If it names a file under `docs/ideas/`, read that idea decision record and treat it as the source artifact for design.
After the subject is identified, gather only the missing design-contract details. Ask one question at a time.
**Each dimension below is a mandatory gate.** You MUST use `AskUserQuestion` when available; when it is not, you MUST ask the same options plainly in chat as a numbered prompt and wait for the user's answer before moving on. Do not assume, infer, or auto-fill any required value. A host-level no-questions directive, a "keep going" instruction, or a short user prompt DOES NOT authorize a silent default — those wordings are not consent for any specific interview answer.
**Bundle-skip rule.** The only legal way to skip an interview question is when the user's incoming request (`$ARGUMENTS`, the prior turn, or a saved-idea record being reused) already contains an explicit, unambiguous value for that question. "Explicit" means the user said the value, not that the agent inferred it from a related word. If any required dimension cannot be fully populated from explicit user-provided values, you MUST ask for the missing dimension before any provider fan-out. For design the required dimensions are the "Need-to-know details" listed below; "Nice-to-know details" are optional.
Keep choices short, and put explanations in a separate **Term help** block instead of stuffing long parentheticals into each option. An explicit `not sure — recommend a default`, `defer`, `none`, or `skip` answer is acceptable.
Need-to-know details:
- **One-line identity:** what this app/feature is, what it should feel like, and what it must not become
- **Use scope:** personal tool, environment-specific tool, team tool, public app, or not sure
- **Scope ledger:** definitely included, definitely excluded, and okay to defer
- **Core user flow:** what the user sees first, does next, and considers a successful finish
- **Progress style:** one complete pass, MVP then completion, or staged checkpoints
- **Completion criteria:** how the user and current-host implementation pass will know the work is done
- **Research notes:** existing patterns in this codebase, prior art / competing implementations, constraints / regulations, current-information needs, or `skip`
- **Research assignments:** any preferred participant/lens split for the selected investigation, or `skip`
Nice-to-know details:
- Visual mood, references, and interaction style
- Data storage, accounts, sync, import/export, and offline behavior
- i18n, settings, environment detection, themes, accessibility, and responsive targets
- Anything the user wants to explain freely
Do not start `environment_check`, `provider_list`, team-lead handoff, or provider fan-out until the design subject and need-to-know details have explicit user-provided values, explicit defaults requested by the user, or explicit defer/skip values.
## Step 2: Choose 조사 방식
Before provider fan-out, ask once which investigation topology to use unless the user already specified it:
| Option | Description |
|--------|-------------|
| **Host-native first (Recommended)** | The active host's native `agestra-research` agent inspects the codebase and prepares the first design evidence packet; providers challenge and debate it. Record internally as `host-seeded`. |
| **Council Research** | Host and providers independently investigate design options with assigned lenses before consolidation and debate. |
| **Provider-seeded Research** | One selected provider creates the first design seed/evidence artifact; host and other providers challenge it. |
This is a mandatory design selection gate. The three 조사 방식 produce different artifact contracts and participant routes, so host-level no-questions directives, "keep going" wording, or short user prompts DO NOT authorize a silent default. Always present the three options through `AskUserQuestion` (or the host equivalent), each with a one-line description, and wait for the user's explicit choice before any provider fan-out. If Provider-seeded Research is selected and the seed provider is not explicit, record the seed provider as pending; after provider availability is listed, ask which available provider should seed. Do not infer it.
Default design principles:
- Prefer maintainable structure and code quality over easy/fast patchwork
- Keep responsibilities separated to avoid spaghetti code
- Improve structure only within the current goal; no unrelated rewrites
- Do not treat implementation errors as a reason to blindly revert approved direction; diagnose and fix forward
- Do not present mock, placeholder, stub, temporary fallback, or shadow-mode behavior as real completion
- List included, excluded, and deferred items, then get explicit user approval before implementation begins. Use `AskUserQuestion` when available, or a plain numbered prompt as fallback.
- Put an Implementation Progress section at the top of the design document, initialized with Planned rows for the included scope and evidence needed for verification
## Step 3: Route execution
Call `environment_check` and `provider_list` to determine which providers and execution options are available.
Respect the providers list verbatim. A provider marked `Not found`, unavailable, or disabled by setup MUST NOT be invoked.
**No-provider stop path:**
Stop Agestra orchestration and tell the user to run `/agestra setup` to enable a provider, or ask the current host to do design work directly outside Agestra. Do not spawn a host specialist from this command.
**Provider-backed path — 1+ external providers available (multi-AI):**
Hand off to the `agestra:agestra-team-lead` agent with multi-AI mode **pre-selected**. Provider-backed design uses the selected research topology flow:
```text
호스트가 조사한다.
호스트가 정리한다.
시스템이 토론한다.
호스트가 문서화한다.
```
External AI research and debate run in separate fresh sessions, even when the same provider participates in both phases. Build a self-contained handoff packet:
- **Domain:** `design`
- **Mode:** `multi-ai` (pre-selected — team-lead must NOT re-ask orchestration mode)
- **Design subject:** `$ARGUMENTS` or the user's clarified topic
- **Design intake answers:** one-line identity, use scope, included/excluded/deferred scope, core flow, progress style, completion criteria, visual/technical constraints, and term-help assumptions
- **Idea decision record:** path under `docs/ideas/` if the design came from a saved idea
- **User constraints:** any explicit constraints provided
- **Workflow profile:** design profile with `workflow: "design"`, design `questionSet`, prompt pack, and `evidencePolicy`
- **Research topology / 조사 방식:** selected in Step 2 (`host-seeded`, `council`, `provider-seeded`, or `automatic`); seed or research findings become `aggregation.items`
- **Host-native route:** for Host-native first (`host-seeded`), run active-host `agestra-research` before external provider fan-out; route any host debate participant to `agestra-debate` with `participant_routes`; do not substitute the current host's external CLI provider for this native role
- **Research notes:** what the selected investigation should look for (existing patterns, prior art, constraints, current-information needs)
- **Research assignments:** optional participant/lens rows for `research_assignments`
- **Available providers:** from `environment_check` / `provider_list`
- **Requested providers:** explicit names captured from the user's wording (e.g. `[codex, gemini]`); otherwise "all available"
- **Locale:** from `setup_status`
- **Target workspace root:** absolute project folder if the user supplied or implied one; pass it to workspace/debate MCP calls as `workspace_base_dir`
- **Progress contract:** surface concise phase updates every 30-60 seconds; poll `agent_debate_status` or `run_observable_events` with a cursor when available; if trace is `cold-start`, report the current local phase and keep monitoring
- **Original user request:** preserve verbatim
Team-lead owns the rest:
- Building the participant team from focused research lenses, explicit host-turn debate participants, and external providers when applicable
- Resolving the selected research topology, then calling `agent_research_start` when investigation fan-out is required; call debate-only `agent_consensus_start` only after `aggregation.json` has been inspected and approved.
- Ensuring external AI research and debate use separate fresh sessions.
- Never creating a bundled research pseudo-participant and never carrying research bundles through legacy source-document fields.
- Inspecting `research_submissions.json`, `research_transcript.json`, `aggregation.json`, `debate_transcript.json`, `workflow_result.json`, the threaded aggregation document, and the concise final decision document under `docs/reports/design/`.
- Returning the research artifact paths, accepted decisions, excluded options, disputed items, and the final design document path under `docs/plans/`.
**Do NOT from this command:**
- Call `agent_consensus_start`, `agent_debate_*`, `ai_chat`, or other consensus tools directly
- Spawn deleted legacy specialist agents directly; design perspective is provided through lenses and the reduced host-native agents
- Build individual documents or hand-edit generated debate/synthesis Markdown
Direct execution from this command bypasses team-lead's capability-based routing and optional trace-assisted signals (`trace_summary`), task design, and consistency enforcement. Always go through team-lead in the provider-backed path.
## Step 4: Present the result
When team-lead returns:
- Name the source idea decision document path under `docs/ideas/` when one was used
- Name the synthesis document path, debate Markdown path, consensus JSON ledger path
- Summarize accepted design decisions, excluded options, and unresolved/disputed items
- Show the final implementation scope ledger: included, excluded, deferred
- Surface technical choices, impossible/unstable parts, and completeness risks
- Surface the mock/fallback/shadow-mode policy and any temporary behavior removal conditions
- Confirm the progress plan and checkpoints
- Confirm the top-level Implementation Progress table exists and starts with Planned items, not fake completion
- Ask the user to approve the final design contract before implementation planning begins. Use `AskUserQuestion` when available, or a plain numbered prompt as fallback. Do not infer approval.
- Preserve each provider's rationale for disputed positions
- Communicate in the user's language
-151
commands/idea.md
---
description: "Discover improvements by comparing with similar projects and collecting feedback"
argument-hint: "[topic or project area]"
---
You are executing the `/agestra idea` command.
**Topic:** $ARGUMENTS
Plain review/QA/check requests without `/agestra` or explicit multi-AI/provider wording stay with the current host; they are not Agestra natural-language auto-triggers.
Agestra natural-language routing requires explicit Agestra/multi-AI/provider wording such as "Agestra", "아제스트라", "multiple AIs", "all AIs", "other AI", "multi-AI", "Codex and Gemini", "provider comparison", or "프로바이더 비교". Explicit `/agestra ...` commands remain supported.
Host interaction fallback: when this workflow says `AskUserQuestion`, use a structured question UI if the current host exposes one. If it is unavailable (for example, in Codex), ask the same question plainly in chat, present the same options, and wait for the user's answer.
## Step 0: Setup preflight (MANDATORY)
Before anything else, call `setup_status`. If it reports `Setup required: yes` or `Current config: not found`, **automatically enter the interactive setup flow before continuing**:
1. Invoke the `agestra:setup` skill or run `/agestra setup` inline — detect providers, ask for selection + locale, call `setup_apply`.
2. After setup writes the config, resume this `/agestra idea` command **from Step 1**, preserving the original `$ARGUMENTS` topic. Do not ask the user to retype it.
Rationale: Agestra's path resolver uses a single shared `providers.config.json` resolved through `AGESTRA_CONFIG_PATH` or `~/.agestra/providers.config.json` (existing legacy `$CLAUDE_PLUGIN_ROOT/providers.config.json` remains readable). Without it, auto-detect silently enables whatever is installed and there is no configured locale, which has caused disabled providers to participate in past runs. Setup is the only sanctioned way to pick the active set. Do not silently choose defaults or write config without the user's provider/language choices.
Before any provider fan-out, run the shared workspace trust preflight for the exact current project root. If supported providers are blocked, ask once whether to register only this project folder. This is a security approval gate, not a clarifying question; "keep going" / no-questions instructions are not approval. After approval, call `provider_trust_apply` once per blocked provider. Use `provider_trust_apply_all` only when the host permission model explicitly allows batch trust changes. If approval cannot be obtained, skip blocked providers.
## Step 1: Determine topic
If `$ARGUMENTS` is empty, first identify the exploration starting point using AskUserQuestion, or a plain numbered prompt if structured choices are unavailable:
| Option | Description |
|--------|-------------|
| **Existing project** | Find additions, improvements, user-facing changes, or future inspiration for the current project |
| **New project idea** | Explore a new app, game, tool, website, service, or rough keyword cluster |
| **Use recent context** | Turn the current conversation into an idea exploration topic |
Then gather only the missing details, one question at a time.
**Each dimension below is a mandatory gate.** You MUST use `AskUserQuestion` when available; when it is not, you MUST ask the same options plainly in chat as a numbered prompt and wait for the user's answer before moving on. Do not assume, infer, or auto-fill any required value. A host-level no-questions directive, a "keep going" instruction, or a short user prompt DOES NOT authorize a silent default — those wordings are not consent for any specific interview answer.
**Bundle-skip rule.** The only legal way to skip an interview question is when the user's incoming request (`$ARGUMENTS`, the prior turn, or a saved-idea record being reused) already contains an explicit, unambiguous value for that question. "Explicit" means the user said the value, not that the agent inferred it from a related word. If any required dimension cannot be fully populated from explicit user-provided values, you MUST ask for the missing dimension before any provider fan-out. For idea exploration the required dimensions are listed under "For **Existing project**, collect:" or "For **New project idea**, collect:" below depending on the selected starting point.
Include a skip option where useful so the user can explicitly answer `none`, `unspecified`, or `skip`.
For **Existing project**, collect:
- **Intent:** additions, improvements, or broader inspiration for where the project could go next
- **Idea areas:** design, usability, onboarding, new features, automation, performance, accessibility, docs, DX, integrations, monetization, community, or other
- **User wishes:** user requests, complaints, positive reactions, or "people seem to want..." signals, or `none`
- **Research notes:** competitor landscape, positive/negative user reactions, current-information needs, source constraints, or `skip`
- **Research assignments:** any preferred participant/lens split for the selected investigation, or `skip`
- **Protected identity/boundaries:** what should not change, or `unspecified`
- **Free notes:** anything else the user wants to say, or `skip`
For **New project idea**, collect:
- **Kind:** game, information collection app, creation/editing tool, website/content site, productivity or automation tool, learning app, community/social app, commerce/marketplace, dashboard, developer tool, AI assistant, browser extension/plugin, mobile app, desktop app, API/library/service, or other
- **Seed:** what the user wants to make; a few rough keywords are enough
- **Audience:** who would use it, or what situation it serves
- **Must-have:** one point that should absolutely exist
- **References:** apps, games, sites, or tools to borrow from or react against, or `none`
- **Difference:** how this should feel different from existing apps, or `unspecified`
- **Research notes:** similar apps, competitor/user-reaction depth, current-information needs, source constraints, or `skip`
- **Research assignments:** any preferred participant/lens split for the selected investigation, or `skip`
- **Free notes:** rough thoughts are welcome, or `skip`
Do not start `environment_check`, `provider_list`, team-lead handoff, or any provider fan-out until all required fields for the selected idea mode have explicit user-provided values or explicit skip values.
Idea exploration should stay broad and creative. Do not filter primarily by implementation difficulty; feasibility, MVP scope, and build strategy belong in the later `/agestra design` step after the user chooses an idea.
## Step 2: Choose 조사 방식
Before provider fan-out, ask once which investigation topology to use unless the user already specified it:
| Option | Description |
|--------|-------------|
| **Host-native first (Recommended)** | The active host's native `agestra-research` agent prepares the first evidence packet, then providers challenge and debate it. Fastest and lowest-cost default. Record internally as `host-seeded`. |
| **Council Research** | Host and providers independently investigate assigned lenses before consolidation and debate. Stronger for broad/open-ended exploration. |
| **Provider-seeded Research** | One selected provider creates the first seed/evidence artifact, then host and other providers challenge it. |
This is a mandatory design selection gate. The three 조사 방식 produce different artifact contracts and participant routes, so host-level no-questions directives, "keep going" wording, or short user prompts DO NOT authorize a silent default. Always present the three options through `AskUserQuestion` (or the host equivalent), each with a one-line description, and wait for the user's explicit choice before any provider fan-out. If Provider-seeded Research is selected and the seed provider is not explicit, record the seed provider as pending; after provider availability is listed, ask which available provider should seed. Do not infer it.
Provider-backed `/agestra idea` uses the selected research topology flow:
```text
호스트가 조사한다.
호스트가 정리한다.
시스템이 토론한다.
호스트가 문서화한다.
```
External AI research and debate run in separate fresh sessions, even when the same provider participates in both phases. If the user explicitly wants to bypass research, route the work to the active host outside Agestra instead.
## Step 3: Route execution
Call `environment_check` and `provider_list` to determine available providers.
Respect the providers list verbatim. A provider marked `Not found` or missing from `environment_check` MUST NOT be invoked (the `enabled:false` opt-out is honored at registration).
**No-provider stop path:**
Stop Agestra orchestration and tell the user to run `/agestra setup` to enable a provider, or ask the current host to do idea exploration directly outside Agestra. Do not spawn a host specialist from this command.
**Provider-backed path — 1+ external providers available (multi-AI):**
Hand off to the `agestra:agestra-team-lead` agent with multi-AI mode **pre-selected**. Build a self-contained handoff packet:
- **Domain:** `idea`
- **Mode:** `multi-ai` (pre-selected — team-lead must NOT re-ask orchestration mode)
- **Idea mode:** `A` (existing project) or `B` (new project) — from the starting point above, or team-lead detects from project state when the user already provided a topic
- **Topic:** `$ARGUMENTS` or the user's clarified topic
- **Interview answers:** the details collected above, including research notes, research assignments, and free notes
- **Workflow profile:** idea profile with `workflow: "idea"`, idea `questionSet`, prompt pack, and `evidencePolicy`
- **Research topology / 조사 방식:** selected in Step 2 (`host-seeded`, `council`, `provider-seeded`, or `automatic`); seed or research findings become `aggregation.items`
- **Host-native route:** for Host-native first (`host-seeded`), run active-host `agestra-research` before external provider fan-out; route any host debate participant to `agestra-debate` with `participant_routes`; do not substitute the current host's external CLI provider for this native role
- **Research notes:** what the selected investigation should look for
- **Research assignments:** optional participant/lens rows for `research_assignments`
- **Available providers:** from `environment_check`
- **Requested providers:** explicit names captured from user wording; otherwise "all available"
- **Locale:** from `setup_status`
- **Target workspace root:** absolute project folder if the user supplied or implied one; pass it to workspace/debate MCP calls as `workspace_base_dir`
- **Progress contract:** surface concise phase updates every 30-60 seconds; poll `agent_debate_status` or `run_observable_events` with a cursor when available; if trace is `cold-start`, report the current local phase and keep monitoring
- **Original user request:** preserve verbatim
Team-lead owns the rest:
- Building the participant team from idea research lenses, explicit host-turn debate participants, and external providers. External providers are MCP/CLI/chat participants only.
- Resolving the selected research topology, then calling `agent_research_start` when investigation fan-out is required; call debate-only `agent_consensus_start` only after `aggregation.json` has been inspected and approved.
- For research fan-out, pass the idea workflow profile, prompt pack, `questionSet`, and `evidencePolicy` to `agent_research_start`.
- Ensuring external AI research and debate use separate fresh sessions.
- Never creating a bundled research pseudo-participant and never carrying research bundles through legacy source-document fields.
- Writing the project-facing idea decision record under `docs/reports/idea/YYYY-MM-DD-idea-<session-id>-result.md` from the threaded aggregation document, JSON artifacts, `workflow_result.json`, and the user's interview answers. Preserve disputed positions and weak-evidence flags rather than averaging them away.
- Inspecting `research_submissions.json`, `research_transcript.json`, `aggregation.json`, `debate_transcript.json`, `workflow_result.json`, the threaded aggregation document, and the concise final document.
- Returning the research artifact paths, accepted/excluded/disputed items, carry-forward ideas, weak-evidence flags, and the `docs/reports/idea/` decision document path.
**Do NOT from this command:**
- Call `agent_consensus_start`, `agent_debate_*`, or `ai_chat` directly
- Spawn deleted legacy specialist agents directly; idea perspective is provided through research lenses and the reduced host-native agents
- Build individual documents or hand-edit generated debate/synthesis Markdown
Writing the final project-facing idea decision record under `docs/reports/idea/` is allowed and expected after the user chooses or approves ideas. `.agestra/workspace/` is the internal research/debate workspace, not the user's primary browsing surface.
Direct execution bypasses team-lead's capability-based routing, optional trace-assisted signals, and consistency enforcement. Always go through team-lead in the provider-backed path.
## Step 4: Present to the user
When team-lead returns:
- Name the debate document, consensus JSON ledger, and final synthesis document when the structured session is finalized
- Separate research-backed opportunities, hypotheses, risky but interesting ideas, duplicates, weakly grounded ideas, and recommended next directions
- Name the idea decision document under `docs/reports/idea/` after the user chooses or approves ideas
- Show ideas grouped as Make Soon, Explore Next, and Inspiration Bank when available
- In terminal/chat, show a title-only list first and point the user to the synthesis document for details
- Explain ledger-accepted ideas as "worth carrying forward", not as MVP approval or implementation consensus
- Explain excluded and still-open ideas in plain language without flattening dissent
- Point out the 2-3 best candidates to take into `/agestra design`, where feasibility and scope will be evaluated
- If no idea has been selected yet, ask which idea or bundle of ideas should be saved before writing the `docs/reports/idea/YYYY-MM-DD-idea-<session-id>-result.md` decision record. Use `AskUserQuestion` when available, or a plain numbered prompt as fallback. Do not infer the saved idea selection.
- Communicate in the user's language
-162
commands/qa.md
---
description: "Verify implementation against a design document with optional E2E/runtime checks"
argument-hint: "[design doc, feature, diff, or implemented scope]"
---
You are executing the `/agestra qa` command.
**Target:** $ARGUMENTS
Plain review/QA/check requests without `/agestra` or explicit multi-AI/provider wording stay with the current host; they are not Agestra natural-language auto-triggers.
Agestra natural-language routing requires explicit Agestra/multi-AI/provider wording such as "Agestra", "아제스트라", "multiple AIs", "all AIs", "other AI", "multi-AI", "Codex and Gemini", "provider comparison", or "프로바이더 비교". Explicit `/agestra ...` commands remain supported.
Host interaction fallback: when this workflow says `AskUserQuestion`, use a structured question UI if the current host exposes one. If it is unavailable (for example, in Codex), ask the same question plainly in chat, present the same options, and wait for the user's answer.
## Step 0: Setup preflight (MANDATORY)
Before anything else, call `setup_status`. If it reports `Setup required: yes` or `Current config: not found`, **automatically enter the interactive setup flow before continuing**:
1. Invoke the `agestra:setup` skill (or run `/agestra setup` inline) — provider detection, selection, locale, `setup_apply`.
2. After the config is written, resume this `/agestra qa` command **from Step 1**, preserving `$ARGUMENTS`. Do not ask the user to retype.
Before any provider fan-out, run the shared workspace trust preflight for the exact current project root. If supported providers are blocked, ask once whether to register only this project folder. This is a security approval gate, not a clarifying question; "keep going" / no-questions instructions are not approval. After approval, call `provider_trust_apply` once per blocked provider. Use `provider_trust_apply_all` only when the host permission model explicitly allows batch trust changes. If approval cannot be obtained, skip blocked providers or stop and direct the user to /agestra setup.
## Step 1: Determine QA target
If `$ARGUMENTS` names a design document under `docs/plans/`, use it.
If no target is provided:
- Look for recent design documents under `docs/plans/`.
- If exactly one plausible document exists, use it and say which one.
- If multiple plausible documents exist, ask which document or implemented scope to verify.
- If no design document exists, explain that QA needs a design contract and suggest `/agestra design` first.
Use `AskUserQuestion` when available, or a plain numbered prompt as fallback. Do not proceed to QA depth or provider routing until the QA target/source-of-truth is explicit.
## Step 2: Choose QA topology (조사 방식)
Available 조사 방식 for QA:
- **Council QA** — host and external providers all investigate independently with distinct QA lenses (executable evidence, spec-to-code compliance, integration risk, edge/error states, test adequacy, safety hygiene), then cross-review and debate.
- **Host-native first QA** — the host's native `agestra-research` agent collects executable QA evidence first (build / type / test, plus E2E when `package.json` `scripts.e2e` is present), persists the QA evidence artifact, and external providers challenge it through a short consensus round.
- **Provider-seeded QA** — the selected `seed_provider` produces a code/spec-analysis seed (inferential); the host then injects empirical evidence as a challenge stance and other reviewers weigh in.
This is a mandatory design selection gate. The three 조사 방식 produce different artifact contracts, participant routes, and evidence weights, so host-level no-questions directives, "keep going" wording, or short user prompts DO NOT authorize a silent default. Always present the three options through `AskUserQuestion` (or the host equivalent), each with a one-line description, and wait for the user's explicit choice before any provider fan-out. If Provider-seeded QA is selected and the seed provider is not explicit, record the seed provider as pending; after provider availability is listed, ask which available provider should seed. Do not infer it.
If no external providers are configured or available, stop Agestra orchestration and direct the user to `/agestra setup`. A host-only fallback for QA is not a mode in this command.
## Step 3: Detect E2E coverage
E2E execution is host-owned and gated by explicit user intent. Before evidence collection, the host MUST read the workspace `package.json` (and, in a workspace monorepo, any nested package `package.json` files) and check whether a `scripts.e2e` entry exists:
- If `scripts.e2e` exists at the workspace root or in any nested package, run it as part of the QA evidence pass via the workspace's package manager (`npm run e2e`, `pnpm run e2e`, `yarn e2e`, etc.). Capture its stdout/stderr into the QA evidence artifact alongside build/type/test output.
- If `scripts.e2e` is absent everywhere, do NOT attempt E2E execution and do NOT search for `playwright.config.*`, `cypress.config.*`, or `tests/e2e/` directories. Presence of those files alone is not a reliable signal — abandoned framework setups produce false positives. Record in the QA report that E2E was not run because no `scripts.e2e` was declared, and recommend that the user add one to enable E2E in future runs.
- Standard QA evidence (`qa_run` for build/type/test) always runs regardless of `scripts.e2e` presence.
Even in multi-AI QA, E2E/runtime execution is host-owned across all three topologies. External providers may review the design, code, host QA report, command output, screenshots, traces, and E2E findings, but they must not run browser/dev-server flows or create persistent E2E files directly.
QA writes a Markdown report under `docs/reports/qa/` unless the user explicitly asks for chat-only output.
## Step 4: Route execution
Call `environment_check` and `provider_list`.
Before any provider fan-out, run workspace trust readiness for the exact target root. If supported providers are blocked, ask once whether to register only this project folder. This is a security approval gate, not a clarifying question; "keep going" / no-questions instructions are not approval. After approval, call `provider_trust_apply` once per blocked provider. Use `provider_trust_apply_all` only when the host permission model explicitly allows batch trust changes. If approval cannot be obtained, skip blocked providers or stop and direct the user to `/agestra setup`. Pass `workspace_base_dir` explicitly to provider readiness/trust and consensus calls whenever the host workspace root may be ambiguous.
Hand off to `agestra:agestra-team-lead`. The canonical QA boundary (Host-native first QA and Provider-seeded QA default):
```text
호스트가 조사한다.
호스트가 정리한다.
시스템이 토론한다.
호스트가 문서화한다.
```
Council QA loosens the first two lines: "호스트와 프로바이더가 함께 조사한다. 호스트가 집계한다." Across all three topologies the closing lines ("시스템이 토론한다." and "호스트가 문서화한다.") are unchanged, and E2E execution remains host-owned.
External AI research and debate run in separate fresh sessions, even when the same provider participates in both phases. Do not carry a research conversation into the debate phase.
### Council QA path
Council QA uses the split research/debate MCP route. Team-lead calls `agent_research_start` with:
- `workflow: "qa"` and the selected QA workflow profile
- the QA `questionSet` and `evidencePolicy`
- The 6 QA lenses as participant assignments: executable evidence, spec-to-code compliance, integration risk, edge/error states, test adequacy, safety hygiene
- Available external providers as participants alongside the host
- The host's empirical evidence (`qa_run` output, E2E output when `scripts.e2e` ran) preserved in `research_submissions.json`, `research_transcript.json`, and `aggregation.json`, with `evidenceType: "empirical"` on every claim derived from the executable artifacts
- Other provider participants emit claims with `evidenceType: "inferential"` (default) unless they were assigned an empirical follow-up lens
Council QA inherits research's council defaults (`max_rounds` follows the research command's default).
### Host-native first QA path
Team-lead runs the host-owned QA evidence pass first via `qa_run` and (when `scripts.e2e` exists) host-run `npm run e2e`, then prepares `aggregation.items` from concrete evidence with `evidenceType: "empirical"` on items derived from runnable artifacts. Then call debate-only `agent_consensus_start` with:
- `workflow: "qa"` as an artifact/report label
- the QA `questionSet`
- the prepared `aggregation`
- the QA `evidencePolicy`
- Exact provider participants
- `participant_routes` for any host-native `agestra-debate` participant
- `max_rounds: 1`
- A bounded participant timeout
External provider stances on host empirical items default to `evidenceType: "inferential"` because they did not run the build/test/E2E themselves; they may set `"mixed"` only when they cite an independent empirical artifact they actually inspected.
### Provider-seeded QA path
Team-lead asks the user which configured, available provider should seed (Step 2 may have already captured this; do not re-ask). Then:
1. Run the selected `seed_provider` to produce a code/spec-analysis seed; record its claims with `evidenceType: "inferential"`.
2. Run the host's empirical evidence pass — host-owned `qa_run` plus host-owned E2E execution when `scripts.e2e` exists — and append host claims with `evidenceType: "empirical"`. Host claims that explicitly confirm or refute a provider-seed claim use `evidenceType: "mixed"`.
3. Call debate-only `agent_consensus_start` with `workflow: "qa"`, the QA `questionSet`, prepared `aggregation`, `evidencePolicy`, the seed provider + at least one reviewer + the host-debate participant route, `max_rounds: 1`, and a bounded participant timeout.
### No-provider stop path
If no external providers are configured or available, stop Agestra orchestration and direct the user to `/agestra setup`. Do not spawn a provider-backed consensus with zero providers, and do not silently substitute a host-only fallback.
### Handoff packet (all three paths)
Build a self-contained handoff packet with:
- **Domain:** `qa`
- **Topology (조사 방식):** Council QA / Host-native first QA / Provider-seeded QA (selected by the user in Step 2; do not re-ask)
- **Seed provider:** when topology is Provider-seeded QA
- **QA target:** from Step 1
- **E2E status:** ran / skipped, with the reason ("scripts.e2e present in {path}" or "no scripts.e2e declared")
- **E2E/runtime execution:** host-owned only; external providers cross-validate artifacts and findings, not browser/dev-server execution
- **Design doc reference:** path under `docs/plans/`
- **Report artifact path expectation:** `docs/reports/qa/YYYY-MM-DD-qa-[target].md`
- **Workflow profile:** QA profile with `workflow: "qa"`, QA `questionSet`, prompt pack, and `evidencePolicy`
- **Connection / Boundary Checks:** API/consumer data shape, route/link mapping, state transition completeness, command/result consistency, and E2E artifact interpretation when E2E ran
- **Evidence type policy:** every claim emitted into the ledger MUST carry `evidenceType`; host empirical claims set `"empirical"` with an `evidence_ref` to the qa_run artifact path/line; provider inferential claims set `"inferential"`; cross-cited host-confirmation-of-provider-claim sets `"mixed"`. Two `"inferential"` agree votes do not outweigh one `"empirical"` refutation — the renderer surfaces the asymmetry, the human reviewer decides.
- **Host-native route:** route any host debate participant to `agestra-debate` with `participant_routes`; do not substitute the current host's external CLI provider for this native role
- **Available providers:** from `environment_check`; include configured providers when their detected model capability is suitable, using read-only QA/review tools so verification cannot modify source files
- **Requested providers:** explicit names captured from user wording; otherwise "all configured and available review-capable providers"
- **QA-only boundary:** QA-only mode does not modify product code; connection or boundary defects are findings until the user approves a separate implementation task
- **JSON finding flow:** candidate findings become `aggregation.items`; debate participants answer each required QA `questionSet` question with allowed verdicts, stance evidence type, and evidence refs; only `workflow_result.json` final-status items affect the final verdict
- **Locale:** from `setup_status`
- **Target workspace root:** absolute project folder if the user supplied or implied one; pass it to workspace/debate MCP calls as `workspace_base_dir`
- **Progress contract:** surface concise phase updates every 30-60 seconds; poll `agent_debate_status` or `run_observable_events` with a cursor when available; if trace is `cold-start`, report the current local phase and keep monitoring
- **Original user request:** preserve verbatim
Team-lead polls `agent_debate_status` and `run_observable_events` when a locator is available, then surfaces concise progress at least every 30-60 seconds while provider work is running. When the status reports pending host turns, team-lead dispatches the native `agestra-debate` agent and submits the JSON with `agent_consensus_submit_turn`. If the current host cannot surface progress from a background team-lead, the caller must poll and relay progress, or stop and direct the user to `/agestra setup`.
### Council QA MCP routing note
Council QA is the topology that calls `agent_research_start` before debate. Host-native first QA and Provider-seeded QA may prepare `aggregation.items` directly, but all three topologies start debate with `agent_consensus_start` using `workflow`, `questionSet`, `aggregation`, and `evidencePolicy`. The debate engine does not branch on `workflow`; QA behavior comes from the supplied profile and question set.
## Step 5: Present the final result
When QA returns:
- State QA topology (Council QA / Host-native first QA / Provider-seeded QA)
- State whether E2E was run, and the reason (scripts.e2e path or "no scripts.e2e declared")
- Link or name the design document used
- Link the QA report artifact under `docs/reports/qa/`
- Include the Observable events artifact path and `run_observable_events` locator hint when `qa_run` returned one
- Show PASS / CONDITIONAL PASS / FAIL
- In Council QA, Host-native first QA, and Provider-seeded QA modes, summarize participants, assigned lenses, accepted ledger items, excluded ledger items, open/opinion items, consensus, notable dissenting findings, and any empirical-vs-inferential evidence asymmetries flagged in the report ledger
- Summarize progress-table mismatches, design gaps, build/test failures, E2E failures, and basic safety hygiene risks
- If persistent E2E coverage is missing, list the recommended scenarios and record the gap as residual risk. Do not ask Agestra to create or update test files.
- Recommend `/agestra review` for critique or `/agestra security` for dedicated security audit when needed
- Communicate in the user's language
-122
commands/security.md
---
description: "Run a dedicated security audit for secrets, auth, file access, network exposure, and unsafe defaults"
argument-hint: "[target file, directory, feature, app, or diff]"
---
You are executing the `/agestra security` command.
**Target:** $ARGUMENTS
Plain review/QA/check requests without `/agestra` or explicit multi-AI/provider wording stay with the current host; they are not Agestra natural-language auto-triggers.
Agestra natural-language routing requires explicit Agestra/multi-AI/provider wording such as "Agestra", "아제스트라", "multiple AIs", "all AIs", "other AI", "multi-AI", "Codex and Gemini", "provider comparison", or "프로바이더 비교". Explicit `/agestra ...` commands remain supported.
Host interaction fallback: when this workflow says `AskUserQuestion`, use a structured question UI if the current host exposes one. If it is unavailable (for example, in Codex), ask the same question plainly in chat, present the same options, and wait for the user's answer.
## Step 0: Setup preflight (MANDATORY)
Before anything else, call `setup_status`. If it reports `Setup required: yes` or `Current config: not found`, **automatically enter the interactive setup flow before continuing**:
1. Invoke the `agestra:setup` skill (or run `/agestra setup` inline) — provider detection, selection, locale, `setup_apply`.
2. After the config is written, resume this `/agestra security` command **from Step 1**, preserving `$ARGUMENTS`. Do not ask the user to retype.
Before any provider fan-out, run the shared workspace trust preflight for the exact current project root. If supported providers are blocked, ask once whether to register only this project folder. This is a security approval gate, not a clarifying question; "keep going" / no-questions instructions are not approval. After approval, call `provider_trust_apply` once per blocked provider. Use `provider_trust_apply_all` only when the host permission model explicitly allows batch trust changes. If approval cannot be obtained, skip blocked providers.
## Step 1: Determine security scope
If `$ARGUMENTS` is provided, use it as the target.
If empty, ask what to audit:
| Option | Description |
|--------|-------------|
| **Recent changes** | Audit the current diff or newly implemented feature |
| **Whole project** | Audit the project as a whole |
| **Specific surface** | Auth, file access, API keys, uploads, browser extension, desktop app, local server, payments, public deployment, etc. |
**Each dimension below is a mandatory gate.** You MUST use `AskUserQuestion` when available; when it is not, you MUST ask the same options plainly in chat as a numbered prompt and wait for the user's answer before moving on. Do not assume, infer, or auto-fill any required value. A host-level no-questions directive, a "keep going" instruction, or a short user prompt DOES NOT authorize a silent default — those wordings are not consent for any specific interview answer.
**Bundle-skip rule.** The only legal way to skip an interview question is when the user's incoming request (`$ARGUMENTS`, the prior turn, or a saved design record being reused) already contains an explicit, unambiguous value for that question. "Explicit" means the user said the value, not that the agent inferred it from a related word. If any required dimension cannot be fully populated from explicit user-provided values, you MUST ask for the missing dimension before any provider fan-out. For security the required dimensions are the security target/surface (Step 1) and security depth (Step 2); tool-permission approvals are a separate gate addressed later in this step.
Do not proceed to depth selection or provider routing until the security target/surface is explicit.
## Step 2: Choose security depth
Ask which depth to use:
| Option | Description |
|--------|-------------|
| **Basic Safety Audit (Recommended)** | Secrets, dangerous file/command/network behavior, unsafe defaults, obvious auth gaps, and public-exposure risks |
| **Full Security Review** | Threat model, auth/authz, injection/XSS/CSRF/CORS, storage/privacy, dependency/supply-chain, logging, deployment, and abuse cases |
| **Specific Surface** | Focus on one named risk surface |
Warn that Full Security Review takes more time and tokens.
Use `AskUserQuestion` when available, or a plain numbered prompt as fallback. Do not infer depth unless the request already clearly asks for Basic, Full, or a specific surface.
Ask separately before any tool-assisted scan that installs tools, contacts package registries, uses network access, or produces large logs. The user must approve the exact tool, command, scope, expected time, privacy/telemetry behavior, and artifact path. If the user declines, continue with manual/code-based review and list the skipped checks as residual risk.
Then ask research notes before provider fan-out: secrets / API key surfaces, auth / authz boundaries, file / command execution paths, network exposure, dependency / supply-chain concerns, unsafe defaults, or `skip`. Ask whether any provider or lens should receive a specific research assignment, or whether team-lead should choose.
## Step 3: Choose 조사 방식
Before provider fan-out, ask once which investigation topology to use unless the user already specified it:
| Option | Description |
|--------|-------------|
| **Host-native first (Recommended)** | The active host's native `agestra-research` agent prepares bounded security evidence first; providers challenge and debate the prepared findings. Record internally as `host-seeded`. |
| **Council Research** | Host and providers independently inspect assigned security surfaces before consolidation and debate. |
| **Provider-seeded Research** | One selected provider creates the first security seed/evidence artifact; host and other providers challenge it. |
This is a mandatory design selection gate. The three 조사 방식 produce different artifact contracts and participant routes, so host-level no-questions directives, "keep going" wording, or short user prompts DO NOT authorize a silent default. Always present the three options through `AskUserQuestion` (or the host equivalent), each with a one-line description, and wait for the user's explicit choice before any provider fan-out. If Provider-seeded Research is selected and the seed provider is not explicit, record the seed provider as pending; after provider availability is listed, ask which available provider should seed. Do not infer it.
## Step 4: Route execution
Call `environment_check` and `provider_list`.
**No-provider stop path:**
Stop Agestra orchestration and tell the user to run `/agestra setup` to enable a provider, or ask the current host to run a security review directly outside Agestra. Do not spawn a host specialist from this command.
**Provider-backed path — 1+ external providers available (multi-AI):**
Hand off to `agestra:agestra-team-lead`. Provider-backed security uses the selected research topology flow:
```text
호스트가 조사한다.
호스트가 정리한다.
시스템이 토론한다.
호스트가 문서화한다.
```
External AI research and debate run in separate fresh sessions, even when the same provider participates in both phases. Build a self-contained handoff packet:
- **Domain:** `security`
- **Mode:** `multi-ai`
- **Security target:** from Step 1
- **Security depth:** from Step 2
- **Risk surfaces:** explicit user selections or detected surfaces
- **Tool permission choices:** approved / declined / not asked, with exact approved commands if any
- **Report artifact path expectation:** `docs/reports/security/YYYY-MM-DD-security-[target].md`
- **Workflow profile:** security profile with `workflow: "security"`, security `questionSet`, prompt pack, and `evidencePolicy`
- **Research topology / 조사 방식:** selected in Step 3 (`host-seeded`, `council`, `provider-seeded`, or `automatic`); seed or research findings become `aggregation.items`
- **Host-native route:** for Host-native first (`host-seeded`), run active-host `agestra-research` before external provider fan-out; route any host debate participant to `agestra-debate` with `participant_routes`; do not substitute the current host's external CLI provider for this native role
- **Research notes:** what the selected investigation should look for (secrets/keys, auth/authz boundaries, file/command execution, network exposure, dependency concerns, unsafe defaults)
- **Research assignments:** optional participant/lens rows for `research_assignments`
- **Available providers:** from `environment_check`; include configured providers when their detected model capability is suitable, using read-only security-review tools unless the user explicitly approves a separate implementation task
- **Requested providers:** explicit names captured from user wording; otherwise "all available security-capable"
- **Specialist handoff (host-native security):** when a host-native security lens is needed, team-lead runs that specialist through the active host layer and includes the result in the selected research/consolidation inputs. Do not use host-specialist handoff to create a bundled research participant.
- **Locale:** from `setup_status`
- **Target workspace root:** absolute project folder if the user supplied or implied one; pass it to workspace/debate MCP calls as `workspace_base_dir`
- **Progress contract:** surface concise phase updates every 30-60 seconds; poll `agent_debate_status` or `run_observable_events` with a cursor when available; if trace is `cold-start`, report the current local phase and keep monitoring
- **Original user request:** preserve verbatim
Team-lead owns resolving the selected research topology, then calling `agent_research_start` when investigation fan-out is required. Debate starts only after team-lead inspects `aggregation.json` and calls debate-only `agent_consensus_start` with `workflow`, `questionSet`, `aggregation`, and `evidencePolicy`. Team-lead must ensure external AI research and debate use separate fresh sessions when a research phase is used, must never create a bundled research pseudo-participant, and must never carry research bundles through legacy source-document fields. Inspect `research_submissions.json`, `research_transcript.json`, `aggregation.json`, `debate_transcript.json`, `workflow_result.json`, the threaded aggregation document, and the concise final decision document under `docs/reports/security/`. The brigade must not run destructive exploit tests and must not install tools or run heavyweight/networked scans without explicit user approval.
## Step 5: Present the result
When security review returns:
- Show SECURITY PASS / PASS WITH HARDENING / SECURITY BLOCK
- Link the security report artifact under `docs/reports/security/`
- Summarize critical/high findings first
- Explain risks in plain language
- List what was not checked
- State which tool-assisted checks were run, skipped, declined, or unavailable
- Recommend QA or general review only if needed
- Communicate in the user's language
dist/bundle.js

Sorry, the diff of this file is too big to display