convez.ai
SkillAutomaçãoAvançado
funky-eyes

Best Copilot

funky-eyes/best-copilot

Workflow multi-agente com 8 especialistas e 39 skills para engenharia séria

Ver no GitHub
BomPluginScore · de 0 a 100

Framework de workflow multi-agente para GitHub Copilot, Claude Code e Codex que implementa disciplina de entrega sênior com especialização de papéis, memória de longo prazo e auto-evolução. Organiza projetos em fluxo estruturado: congelamento de escopo, design antes da implementação, revisão independente e preservação de checkpoints.

Instalação

$npx convez-ai funky-eyes/best-copilot

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
12
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
v0.7.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Coordenar projetos complexos com múltiplos agentes especializados
  • Implementar disciplina de design-antes-código em repositórios
  • Manter memória de contexto e checkpoints entre sessões
  • Automação de revisão, QA, segurança e verificação de evidências

Veredito

Solução madura e ambiciosa que trata o problema real de falha em tarefas de IA coding: falta de disciplina de entrega. Implementação robusta com suporte a múltiplas plataformas (Codex, Copilot CLI, Claude Code), mas exige investimento inicial significativo em setup e compreensão da arquitetura de agentes.

README

A tradução para o português deste README ainda está na fila.

best-copilot

English | Simplified Chinese | Korean | Japanese

version Codex Copilot CLI Claude Code agents skills license

best-copilot hero

best-copilot is an installable agent-team workflow for serious engineering work in Codex, Copilot CLI, and Claude Code. It gives a repository a senior delivery flow: initialize facts, freeze scope, design before building, implement through specialist roles, review independently, verify with evidence, and preserve a resume point for the next session.

Codex uses .codex-plugin/plugin.json, .agents/plugins/marketplace.json, .agents/skills -> ../skills, and .codex/agents/*.toml. Copilot CLI uses root agents/ and skills/ through plugin.json. Claude Code uses the claude-plugin/ package: claude-plugin/.claude-plugin/plugin.json, claude-plugin/skills -> ../skills, and claude-plugin/agents -> ../claude-agents. Repository-level rules live in .github/instructions/**.

Why It Exists

Large AI coding tasks fail when they jump straight from a vague request to a patch. best-copilot adds the missing delivery discipline:

  • One senior entry point: Senior Project Expert owns intent, scope, dispatch, fan-in, closeout, and reusable workflow signals.
  • Eight specialist agents: planning, architecture, implementation, frontend, QA, security, root-cause fixing, and specification work have separate ownership.
  • Thirty-nine skills: role workflows, bootstrap, search, planning, workspace isolation, TDD, design review, execution, Java/Python coding guidelines, verification, branch closeout, frontend audit, workflow evolution, and a Senior Project Expert compatibility entrypoint are installable skills.
  • Target-local memory and spec: installed projects keep facts, workstreams, memory, and specs inside the target repository, not in the plugin package.
  • Evidence-first closure: "done" requires command output, static checks, browser evidence, or an explicit blocker.

Install

Codex

Codex supports plugins as installable bundles for reusable skills, apps, and MCP config. Add this repository as a Codex marketplace, then install the plugin from the Codex plugin directory:

codex plugin marketplace add funky-eyes/best-copilot
codex plugin add best-copilot@best-copilot

For local development from this checkout:

codex plugin marketplace add /absolute/path/to/best-copilot
codex plugin add best-copilot@best-copilot

Codex discovers:

  • plugin metadata from .codex-plugin/plugin.json
  • local/repo marketplace metadata from .agents/plugins/marketplace.json
  • marketplace plugin source from plugins/best-copilot, a real Codex plugin package whose skills folder links to the shared root skills/
  • shared skills from skills/ through the plugin manifest, visible on the installed plugin details page
  • direct repo-scoped shared skills through .agents/skills, which is the path that makes these skills appear in the normal $ skill selector when working from this checkout
  • Codex custom agents from .codex/agents when working from this checkout, after copying that adapter directory into a target repo, or after repo-init-scan runs with Codex compatibility

After installing or editing the plugin, start a new Codex thread/session. Use @best-copilot when you want this workflow from the installed plugin. If you want the individual workflow skills to appear in the normal $ skill selector, expose them through a repo or user skill location such as .agents/skills or ~/.agents/skills.

Codex subagents are configured separately from plugins. The Copilot agents/*.agent.md files and Claude claude-agents/*.md adapters do not become Codex custom agents after plugin installation, so this repository also ships native Codex TOML adapters under .codex/agents. For target repositories, the init helper creates AGENTS.md and the same eight .codex/agents/*.toml adapters when Codex compatibility is requested.

Copilot CLI

Register this repository as a Copilot CLI plugin marketplace:

copilot plugin marketplace add funky-eyes/best-copilot

Install from the registered marketplace:

copilot plugin install best-copilot@best-copilot

Local development uses the same marketplace path:

copilot plugin marketplace add /absolute/path/to/best-copilot
copilot plugin install best-copilot@best-copilot

Current Copilot CLI releases can also install directly from a repository, but the CLI warns that direct installs are deprecated and future releases will support only plugin@marketplace installs:

copilot plugin install funky-eyes/best-copilot

After local edits, reinstall or update the plugin before testing a fresh CLI session. Copilot CLI reads agents and skills from its installed plugin cache.

Claude Code

Claude Code uses its own marketplace system. Add this repository as a Claude Code marketplace, then install the plugin:

/plugin marketplace add funky-eyes/best-copilot
/plugin install best-copilot@best-copilot
/reload-plugins

For local development or direct use from this checkout, load the plugin directory:

claude --plugin-dir /absolute/path/to/best-copilot/claude-plugin

For the reliable Senior Project Expert entrypoint in Claude Code, make that agent own the whole session:

claude --plugin-dir /absolute/path/to/best-copilot/claude-plugin --agent senior-project-expert

After installing the plugin, the same session entry can usually be shortened to:

claude --agent senior-project-expert

Claude Code discovers:

  • marketplace metadata from .claude-plugin/marketplace.json
  • plugin metadata from claude-plugin/.claude-plugin/plugin.json
  • shared skills from skills/ as namespaced slash commands such as /best-copilot:repo-init-gate; if the picker inserts another displayed plugin form, use that exact value
  • Claude-compatible subagents from claude-agents/
  • session PM selection through --agent senior-project-expert or Claude Code's project/user agent setting; /agents and @ typeahead show plugin subagents under scoped names such as best-copilot:senior-project-expert, which should be used for manual @ mentions or explicit Agent-tool dispatch

After local edits or plugin updates, run /reload-plugins inside Claude Code or restart the session.

Usage

Start requirement orchestration with the Senior Project Expert PM coordinator. It owns intent, scope, planning, dispatch, review fan-in, and closeout.

  • Copilot CLI: run /agent, select Senior Project Expert, then describe the work. Copilot uses handoffs: declarations for specialist routing.
  • VS Code extension: manually switch the chat agent to Senior Project Expert, then start the task.
  • Claude Code: the PM is the main session, dispatching to specialists via the Agent tool.
  • Codex: invoke @best-copilot, then ask for the workflow. From this checkout, .agents/skills also exposes the compatibility $senior-project-expert skill to the normal $ skill selector. For parallel work, explicitly ask Codex to spawn subagents; Codex does not auto-spawn subagents only because a plugin is installed.

Claude Code Entry Points

# Recommended: explicit PM agent
claude --agent senior-project-expert
# If Claude reports an agent-name collision, use:
# claude --agent best-copilot:senior-project-expert

# Method 2: set default agent via .claude/settings.json (no need to specify each time)
# Add to target repo's .claude/settings.json:
# { "agent": "senior-project-expert", "worktree": { "baseRef": "head" } }

# Local plugin development
claude --plugin-dir /absolute/path/to/best-copilot/claude-plugin --agent senior-project-expert

How Claude Code Multi-Agent Works

The PM (senior-project-expert) as the main session receives user requirements and then:

  1. Runs /best-copilot:repo-init-gate for initialization preflight
  2. Analyzes intent, classifies work mode (micro/standard/full), freezes the dispatch packet
  3. Spawns specialist subagents via the Agent tool using the scoped names shown by /agents (e.g., best-copilot:technical-architect, best-copilot:developer)
  4. Chooses background execution only for independent research/read-only review when permissions are already granted
  5. Runs implementation, fixes, spec/memory writes, and permission-gated verification foreground by default
  6. Uses isolation: "worktree" for implementation tasks that might conflict, then collects the worktree path, branch, changed files, and verification evidence
  7. Performs /best-copilot:development-branch-closeout or an equivalent keep / merge / PR / discard decision before claiming isolated worktree changes have landed
  8. Collects results from all subagents, performs fan-in arbitration
  9. Calls /best-copilot:verification-before-completion before final delivery

Available plugin subagents appear scoped in Claude Code: best-copilot:technical-architect, best-copilot:developer, best-copilot:frontend-designer, best-copilot:quality-assurance-expert, best-copilot:security-reviewer, best-copilot:specification-writer, best-copilot:root-cause-fixer.

Claude adapters use Claude model aliases in claude-agents/*.md: GPT-5.4-mapped roles use opus, Gemini-mapped roles use haiku, and Claude Sonnet roles use sonnet. In native Claude Code these aliases preserve the Copilot role tiers inside Claude's model families. If cc-switch, new-api, or another Anthropic-compatible proxy routes those aliases to DeepSeek, Qwen, or another non-Claude backend, first verify the plugin is enabled in that routed session. /plugin list should show best-copilot@best-copilot, /agents should show scoped agents such as best-copilot:senior-project-expert, and proxy allowlists must include "enabledPlugins": {"best-copilot@best-copilot": true} when required. Then treat the backend as degraded until the PM outputs PROVIDER_COMPAT -> INIT_GATE -> CLASSIFY -> FREEZE_PACKET -> LANE_SELECTION, names the required specialist lanes, and reaches repo-init-gate / repo-init-scan before source reading or implementation.

Runtime Adapter Architecture

Three-Layer Isolation Principle

Shared Contract Layer
core-workflow-contract + role-*-workflow per role
        |
        +-- Codex Adapter
        |   .codex-plugin/
        |   .agents/plugins/
        |   .agents/skills -> ../skills
        |   @plugin / $skill, explicit subagents
        |
        +-- Copilot CLI Adapter
        |   agents/*.agent.md
        |   model: GPT-5.4 etc
        |   handoffs: declares
        |   reads skills/ directly
        |
        +-- Claude Code Adapter
            claude-agents/*.md
            model: opus/haiku/sonnet
            Agent tool dispatch
            claude-plugin/{agents,skills} symlinks

Common cross-role rules live in skills/core-workflow-contract/SKILL.md. Each role has its own workflow skill under skills/*-workflow/: senior-project-expert-workflow, specification-writer-workflow, technical-architect-workflow, developer-workflow, frontend-designer-workflow, quality-assurance-workflow, security-reviewer-workflow, and root-cause-fixer-workflow. Codex-only details stay in .codex-plugin/, .agents/, and .codex/agents: plugin metadata, marketplace metadata, direct repo-scoped skill discovery, and Codex custom agent adapters. Copilot-only details stay in agents/: model names, Copilot tools, user-invocable, agents, and handoffs. Claude-only details stay in matching files under claude-agents/: runtime-displayed agent names, Claude model aliases (opus, sonnet, haiku), read-only restrictions, isolation: worktree, and PM-owned foreground/background dispatch policy.

This keeps shared behavior, role-specific behavior, and incompatible runtime metadata isolated while requiring every agent to load both the shared contract and its role workflow.

Skill Loading Rules

ScenarioBehavior
Codex plugin sessionSkills are bundled by .codex-plugin/plugin.json and shown on plugin details; invoke @best-copilot, and explicitly request subagents for parallel work
Codex repo checkout.agents/skills -> ../skills exposes shared skills; .codex/agents/*.toml exposes Codex custom agents
Claude PM main sessionPM's skills: frontmatter declarative preloading
Claude subagent (PM spawn)Subagent loads from its own skills: frontmatter; PM must include task context and required skills in spawn prompt
Claude base sessionAgent's skills: not activated, must call manually
Copilot CLIBody reference is not mechanical preload, packet must include minimal checklist

Claude agent frontmatter normally preloads only core-workflow-contract and the matching role workflow skill. Senior Project Expert also preloads repo-init-gate and repo-init-scan because the init preflight is a mandatory boot gate. Other focused skills such as structured-review, test-driven-development, or web-experience-audit stay on-demand in the agent body to reduce startup context.

Multi-Runtime Comparison

DimensionCodexCopilot CLIClaude Code
Entry@best-copilot for the installed plugin, or senior-project-expert from .codex/agents in repo/custom-agent modeagents/pm-coordinator.agent.mdclaude-agents/senior-project-expert.md (via --agent or .claude/settings.json)
Model specificationCodex runtime/config chooses model unless promptedConcrete names like GPT-5.4 (copilot)model: opus / haiku / sonnet role-tier aliases
Specialist dispatchExplicit Codex subagent/delegation prompts through workflow skillshandoffs: declarations + agent toolPM main session spawns via Agent tool
Parallel executionExplicit user/PM request requiredHandoff declarations handle automaticallyPM chooses background only for safe independent research/review
File isolationCodex sandbox/worktree behaviorCopilot built-inisolation: "worktree" plus PM closeout
User interactionCurrent Codex ask/approval surfacevscode_askQuestions / Asking userBuilt-in AskUserQuestion
Skill discoveryPlugin details from .codex-plugin; normal $ selector from .agents/skills or other skill locationsDirectly reads root skills/claude-plugin/skills -> ../skills symlink
Agent discovery.codex/agents/*.toml custom agentsDirectly reads root agents/claude-plugin/agents -> ../claude-agents symlink
Cross-model routingCodex runtime/config controlledSupported (GPT / Gemini / Claude mixed)Claude model-tier aliases only

Copilot handoffs are fail-closed: each PM handoff prompt requires core-workflow-contract plus the target role workflow skill. If the runtime cannot load those skills, the handoff includes a minimal role checklist fallback; without either, the specialist returns NEEDS_CONTEXT missing_required_skill.

Quick Check

/agent
/skills list

Expected package shape:

best-copilot
├── plugin.json
├── .codex-plugin/
│   └── plugin.json
├── .agents/
│   ├── plugins/
│   │   └── marketplace.json
│   └── skills -> ../skills
├── .claude-plugin/
│   └── marketplace.json
├── claude-plugin/
│   ├── .claude-plugin/
│   │   └── plugin.json
│   ├── .mcp.json
│   ├── agents/ -> runtime-named symlinks to ../claude-agents
│   └── skills -> ../skills
├── marketplace.json
├── agents/
│   ├── pm-coordinator.agent.md
│   ├── tech-architect.agent.md
│   ├── developer.agent.md
│   ├── frontend-designer.agent.md
│   ├── risk-qa.agent.md
│   ├── security-agent.agent.md
│   ├── auto-fixer.agent.md
│   └── spec-writer.agent.md
├── claude-agents/
│   ├── senior-project-expert.md
│   ├── technical-architect.md
│   ├── developer.md
│   ├── frontend-designer.md
│   ├── quality-assurance-expert.md
│   ├── security-reviewer.md
│   ├── root-cause-fixer.md
│   └── specification-writer.md
├── skills/
└── .github/
    ├── instructions/
    └── plugin/

Core Workflow

Every task passes through an observable stage chain visible in the transcript:

INIT_GATE → [INIT_SCAN if needed] → CLASSIFY → FREEZE_PACKET → LANE_SELECTION
  → [ARCHITECT_SDD if full/ambiguous/high-risk] → REVIEW_OR_DISPATCH
  → FAN_IN_ARBITRATION → NEXT_GATE

Behavioral Reliability Gates

FREEZE_PACKET and execution preserve these constraints:

  • State assumptions, tradeoffs, and the simplest viable option; if uncertainty changes implementation, routing, or acceptance criteria, ask instead of guessing.
  • Choose the smallest change that satisfies success criteria; do not add speculative features or abstractions for one-time code.
  • Surgical changes: every changed line should trace to the user goal, acceptance checks, or verification repair; do not tidy adjacent code, comments, or formatting.
  • Read before writing: before code changes, read the target file's public surface/exports, the direct caller/callee, and obvious shared utilities or local patterns.
  • Drive execution with success criteria, constraints, verification, and stop conditions; prescribe steps only when dependencies, safety, or verification require them. Checkpoint significant steps with what was done, verified, and left.

Stage 1: Init Gate (Mandatory Preflight)

Before any substantive work on the target repository, the system runs repo-init-gate — it only reads best-copilot.md from the target repository root, checking whether the frontmatter version matches the current contract version "0.7.0".

repo-init-gate
  │
  ├── version matches → ready → skip, continue to next stage
  │
  └── missing/mismatch/invalid → needs_init
                           │
                           ▼
                    repo-init-scan
                      │
                      ├── Stage 1: repo-init-official
                      │     Runs copilot init or Claude native /init helper
                      │     Output → project.instructions.md
                      │
                      └── Stage 2: repo-init-manual-fallback
                            Manual scan → create scaffolds
                            target-instructions-bootstrap
                            target-memory-bootstrap
                            target-spec-bootstrap
                            │
                            └── Write best-copilot.md sentinel

This is a Fail-Closed design: until init is complete, planning, implementation, or review is not permitted. The system returns BLOCKED rather than continuing from guesses. Only when repo-init-scan reports next_task_ready: yes is entry into subsequent stages permitted.

Stage 2: Task Classification

The system classifies each task into three levels:

LevelApplicable ScenariosProcess Weight
microTiny edits/checks, no public contract, security, or cross-module riskDirect execution
standardBounded file set, single owner surfaceLean packet, focused review
fullAmbiguous, cross-module, public API/schema/auth/dependencies/CI/frontend experienceFull planning, SDD design review, fan-in gates

task_type tracks behavior independently of size: implementation (write/update), design_review (evaluate without implementing), verification (review risk/merge readiness), fix (bounded fix), spec (requirements/design/tasks, no production code).

Stage 3: Freeze Context (Six-Block Dispatch Packet)

The PM freezes intent into a standard six-block dispatch packet (PM Dispatch Packet), the unified cross-role communication protocol:

1. task_intent     — Goal, user path, intent summary, expected outcome, task_type, work_mode
2. frozen_scope    — Scope, non-goals, files involved, files changed, priority/read files, dependencies
3. fact_packet     — Authoritative repo facts, source references, reference files
4. execution_contract — Assumptions, tradeoffs, simplest option, constraints, acceptance checks, verification/context budget, stop conditions, forbidden methods, read-before-write targets
5. review_state    — Subsequent scope, verified items, review lanes, ready artifacts
6. output_contract — Required skills, role checklist fallback, required artifacts, next stage

Why use packets? Because each specialist receives a frozen, bounded context rather than the full conversation history. This prevents "one agent's guess becoming another agent's fact" while ensuring every dispatch is traceable and auditable.

Stage 4: SDD Design Gate

For full, ambiguous, high-risk, public contract, auth/security, dependency, schema, or frontend experience tasks, implementation must first pass through a Technical Architect-led SDD (Spec-Driven Design) brainstorming:

  1. PM dispatches the design task to Technical Architect
  2. Technical Architect conducts SDD design brainstorming and self-reviews/fixes
  3. PM dispatches Developer + QA for a second-round design review
  4. When frontend UI is involved, Frontend Designer joins
  5. Blocking findings are sent back to Technical Architect for fixes; PM only re-runs affected review lanes
  6. Only designs that pass review are allowed to proceed to implementation

For standard tasks, ARCHITECT_SDD is skipped with the reason recorded for efficiency — bounded, non-ambiguous standard work is not forced through architecture SDD.

Stage 5: Parallel Dispatch and Execution

After passing design review, PM breaks work into parallelizable tasks via writing-plans, each with:

  • Independent file ownership and write sets (non-overlapping)
  • Clear dependency relationships and acceptance checks
  • Designated owner lanes and review lanes

Dispatch execution proceeds through subagent-driven-development or executing-plans:

For each ready task:
  1. Build fresh context packet (context-packet-fastpath)
  2. Dispatch implementation to corresponding specialist
     - Technical Architect: full-stack architecture/mainline slices
     - Developer: bounded slices
     - Frontend Designer: UI-owned slices
     - Root Cause Fixer: confirmed failures
  3. Request implementation evidence: files changed, read-before-write evidence, tests/checks run, key output, risks
  4. Stage 1 review: spec/task compliance (requirements, non-goals, file boundaries, acceptance checks)
  5. Stage 2 review: code quality and release risk (maintainability, coupling, security/performance risk, dead code, test sufficiency)
  6. Confirm findings enter fix cycle
  7. PM may only mark task complete after passing all required reviews and verification

Key rule: Stage 1 and Stage 2 reviewers cannot be the implementer. Review lanes follow cross-review rules (see below).

Stage 6: Fan-In Arbitration

PM adjudicates all specialist results by priority:

  1. Blockers: BLOCKED, NEEDS_USER_INPUT, invalid handback, repeated NEEDS_CONTEXT
  2. Security: security, privacy, data loss, auth, dependencies, release, destructive operation risks
  3. Verification: failed/missing verification, unproven completion claims
  4. Scope: spec mismatch, scope creep, write set overlap
  5. Quality: code quality, maintainability, performance, UX, accessibility, test sufficiency
  6. Non-blocking: follow-up notes

When reviewers disagree, PM records decision_provenance (evidence, blocking status, next stage, residual risk). Unresolved conflicts do not allow fan-out or closeout.

Cross-Review Rules

Code Under ReviewReviewer
Developer codeTechnical Architect
Technical Architect codeDeveloper
Developer/Technical Architect frontend codeFrontend Designer
Frontend Designer codeTechnical Architect
All code (final)QA (merge readiness)
Security-sensitive surfacesSecurity Reviewer (mandatory)

Stage 7: Verification and Closeout

Before closing, the system runs verification-before-completion final checks:

  • Requirements/user requests have been satisfied
  • Changes are bounded within task scope
  • No placeholders, dead references, stale names, or broken links
  • Tests/build/browser checks/static verification have been run (or explicitly reported as skipped)
  • Residual risks and next steps are clearly stated
  • Use Native Ask UI for final confirmation/continue (not a plain text summary)

Lean Path for Small Tasks

For micro level tasks, the above flow stays lean — direct execution, skipping SDD design, parallel dispatch, and multi-round review. But even the smallest changes still require verification-before-completion checks before being marked done.

Agent Team

AgentOwnsDoes Not Own
Senior Project ExpertIntent, scope, orchestration, dispatch, fan-in, closeout, evolution signalsDirect production implementation
Specification WriterDiscovery evidence, requirements, design, tasks, ADRs, memory/spec recoveryProduction implementation
Technical ArchitectFull-stack design, SDD brainstorming, API/data/service boundaries, mainline implementation, parallel decomposition, review of Developer/Frontend Designer workFinal frontend polish, task orchestration
DeveloperFrozen implementation slices, implementation-feasibility review, peer review of architect-owned codeArchitecture changes, scope expansion
Frontend DesignerPages, components, interaction, responsive behavior, browser evidence, frontend reviewBackend mainline work
Quality Assurance ExpertFunctional verification, regression risk, code review, merge readiness after peer lanesSecurity review and fixes
Security ReviewerAuth, permissions, sensitive data flow, dependencies, release-surface securityGeneral functional QA
Root Cause FixerFailure triage, minimal patching, regression proofSpeculation-driven refactors

Specialist Communication Protocol

Specialist Ask Boundary

All specialists (non-PM roles) cannot directly ask the user questions. This is a hard constraint:

Specialist needs information
  │
  ├── Missing context → return NEEDS_CONTEXT to PM
  │                      Includes clarification_request + pm_action: "pm_clarify"
  │
  └── Needs user input → return NEEDS_USER_INPUT to PM
                           Includes question, why_blocking, options,
                           safe_default, resume_prompt_for_pm

Only the PM/Coordinator may use the Native Ask mechanism (Copilot: vscode_askQuestions / Asking user; Claude: AskUserQuestion) to question the user.

Native Ask Contract

  • Only top-level sessions or PM/Coordinators may use native asking
  • Each question must allow a free-form answer (fixed-choice UI must include "Custom answer")
  • Claude Code asks through AskUserQuestion: use selectable options plus the built-in custom/Other answer path, not prose-only "which next?" questions
  • Turns must not end with plain text summaries (when Native Ask UI is available)
  • If UI is unavailable and user selection is needed → report BLOCKED missing_native_ask_ui

Structured Specialist Handback

Each specialist returns a standardized structured result:

- task_id:                Task identifier
- current_stage:          Current stage
- status:                 DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT |
                          NEEDS_USER_INPUT | BLOCKED
- summary:                Completion summary
- artifacts:              Artifacts (files, tests, evidence)
- risks:                  Risks
- uncovered_items:        Uncovered items
- recommended_next_stage: Recommended next stage

Memory and Spec System

Dual-Track Persistence

best-copilot maintains two persistence systems in the target repository:

Target Repository
├── spec/                          ← Spec: authoritative source for requirements/design/tasks
│   ├── INDEX.md                   ← Spec routing table
│   └── templates/                 ← Reusable templates
│
├── memories/repo/                 ← Memory: resume index
│   ├── INDEX.md                   ← Memory routing table
│   ├── current-workstreams.md     ← Currently active work
│   ├── project-state.md           ← Project state snapshot
│   ├── decisions.md               ← Decision records
│   └── workflow-rules.md          ← Memory/spec coordination rules
│
├── .github/instructions/          ← Repository-level rules
│   ├── project.instructions.md    ← Project facts (build/test/framework/entry)
│   ├── must.instructions.md       ← Core rules
│   └── skills-index.instructions.md ← Skill routing
│
└── best-copilot.md               ← Init sentinel (version: "0.7.0")

Spec vs Memory Division

DimensionSpecMemory
AuthorityAuthoritative source for requirements/design/tasksResume index — current focus, decisions, last verification, next actions
ContentRequirement docs, design docs, task lists, acceptance checksWorkflow status, verified decisions, resume prompts, compressed facts
ExcludesNo logs, no statusNo requirement specs, no design docs
Coordination rules—Memory never overrides current repo files, command output, system instructions, or explicit user instructions

Progressive Disclosure

Memory uses INDEX.md routing + on-demand loading to control the token budget:

1. Read INDEX.md (routing table)
2. If resuming active work, read current-workstreams.md
3. Follow linked_spec and linked_memory
4. Only load relevant sections of selected memory files
5. Fall back to archive/logs only when source tracing is needed

Each memory file has a load_tier tag: task-active (loaded during active tasks), task-reference (loaded on demand for reference), archive-reference (loaded only during tracing).

Bidirectional Links for MEDIUM/LARGE Work

Medium-to-large work establishes bidirectional links between spec and memory:

  • Each workflow in current-workstreams.md has linked_spec pointing to the corresponding spec
  • Each spec in spec/INDEX.md can back-reference related memory
  • EvolutionEvent records require all fields: signal, target, mutation, validation, rollback, status

Skill Map

AreaSkills
Compatibilitysenior-project-expert
Role Workflowssenior-project-expert-workflow, specification-writer-workflow, technical-architect-workflow, developer-workflow, frontend-designer-workflow, quality-assurance-workflow, security-reviewer-workflow, root-cause-fixer-workflow
Bootstraprepo-init-gate, repo-init-scan, repo-init-official, repo-init-manual-fallback, target-instructions-bootstrap, target-memory-bootstrap, target-spec-bootstrap
Planningbrainstorming, writing-plans, context-packet-fastpath, search-fastpath, spec-execution-fastpath
Executionworkspace-isolation, test-driven-development, executing-plans, subagent-driven-development, dispatching-parallel-agents
Coding Standardstd-java-coding-guidelines, td-python-coding-guidelines
Reviewstructured-review, spec-review-gauntlet, root-cause-investigation, systematic-debugging
Verificationchange-verification, verification-before-completion, development-branch-closeout, web-experience-audit, frontend-design-guardrails
Evolutionevolution-loop

First Use In A Target Repository

Initialization is automatic — there is no need to manually run /init or copilot init. When the PM agent starts, Core Workflow Stage 1 automatically executes repo-init-gate → repo-init-scan; in Claude Code the official stage attempts native /init through the bundled helper before best-copilot creates target instructions, memory, spec scaffolds, and the sentinel.

Just start the PM in Claude Code:

claude --agent senior-project-expert

The initialization flow creates these target-local files:

.github/instructions/project.instructions.md    ← Project facts (build/test/framework/entry)
.github/instructions/must.instructions.md       ← Core rules
.github/instructions/skills-index.instructions.md ← Skill routing
CLAUDE.md                                        ← Claude Code compatibility (optional)
memories/repo/INDEX.md                           ← Resume index routing table
memories/repo/current-workstreams.md             ← Currently active work
spec/INDEX.md                                    ← Spec routing table
spec/templates/                                  ← Reusable templates
best-copilot.md                                  ← Init sentinel (version: "0.7.0")

If required facts or scaffolds cannot be created, the workflow stops as BLOCKED first_use_gate_incomplete — see Core Workflow Stage 1 for the full explanation.

Model Strategy

Each agent declares a model in agents/*.agent.md, and the routing policy is part of the product:

AgentModel
Senior Project ExpertGPT-5.4
Technical ArchitectGPT-5.4
Specification WriterGemini 3.1 Pro (Preview)
DeveloperGemini 3.1 Pro (Preview)
Frontend DesignerGemini 3.1 Pro (Preview)
Quality Assurance ExpertClaude Sonnet 4.6
Security ReviewerGemini 3.1 Pro (Preview)
Root Cause FixerClaude Sonnet 4.6

Native Claude Code uses Claude model aliases. The Claude adapters in claude-agents/*.md preserve role separation and map Copilot tiers to Claude aliases: GPT-5.4 -> opus, Gemini 3.1 Pro (Preview) -> haiku, and Claude Sonnet 4.6 -> sonnet. Proxy routes such as cc-switch or new-api may map those aliases to non-Claude models; that is API compatibility only. For DeepSeek, Qwen, or unknown backends, verify plugin enablement first: /plugin list should include best-copilot@best-copilot, /agents should show scoped plugin agents, and cc-switch / new-api allowlists should contain "enabledPlugins": {"best-copilot@best-copilot": true} when that setting is used. Then run a non-destructive workflow smoke check before real work. Expected behavior: the PM outputs PROVIDER_COMPAT -> INIT_GATE -> CLASSIFY -> FREEZE_PACKET -> LANE_SELECTION, then dispatches the required lanes for the request. If it starts coding, skips init, or skips lanes even with the plugin enabled, use a model/provider that passes the smoke check.

Search Discipline

The system follows strict priority when retrieving information to control token consumption and improve accuracy:

Explicit user path → changed files → frozen files_involved → repo index
  → filename/glob → fixed-string rg -F → regex (last resort)
  • Prefer rg -F fixed-string search for class names, methods, routes, config keys
  • Use regex only when truly ambiguous or when precise search fails, and record the reason
  • Avoid repo-wide regex; scope to the smallest directory; stop after two searches with no new signal
  • Before designing for concurrency/unfamiliar patterns/infrastructure, search for runtime/framework built-ins first (battle-tested → recent trends → first principles)

Anti-Rationalization Checks

Before claiming "done", the system automatically checks these common self-deception patterns:

ExcuseRebuttal
"We'll add tests later"Testing is part of the task, not follow-up work
"It works on my machine"Show the verification command and its output
"It's a small change"Small changes still need bounded verification evidence
"The spec says it's fine"Cite the specific spec line, don't paraphrase

Security Constraints

  • Do not store keys, tokens, credentials, PII, raw long logs, internal hosts, or sensitive paths in instructions, memory, spec, or task logs
  • Public API, schema, auth, dependencies, CI/CD, and release surfaces require blast-radius assessment
  • New behavior and bug fixes should add tests or minimal reproducible checks when practically feasible

Verify This Package

ruby -rjson -e 'JSON.parse(File.read("plugin.json")); JSON.parse(File.read(".codex-plugin/plugin.json")); JSON.parse(File.read("claude-plugin/.claude-plugin/plugin.json")); JSON.parse(File.read(".claude-plugin/marketplace.json")); JSON.parse(File.read("settings.json")); JSON.parse(File.read(".claude/settings.json")); JSON.parse(File.read("marketplace.json")); JSON.parse(File.read(".github/plugin/marketplace.json")); JSON.parse(File.read(".agents/plugins/marketplace.json")); puts "json ok"'
ruby -ryaml -e 'Dir["{agents,skills,claude-agents}/**/*.{md,agent.md}"].sort.uniq.each { |f| s=File.read(f); next unless s.start_with?("---"); YAML.safe_load(s.split("---",3)[1], permitted_classes: [Symbol]); }; puts "frontmatter ok"'
find agents -maxdepth 1 -name '*.agent.md' | sort
find claude-agents -maxdepth 1 -name '*.md' | sort
find skills -maxdepth 3 -name SKILL.md | sort
claude --plugin-dir /absolute/path/to/best-copilot/claude-plugin plugin details best-copilot
git diff --check

The Claude inventory should include Agents (8), Skills (39), and Hooks (0). In /agents Library and @ typeahead, the plugin agents should appear scoped as best-copilot:senior-project-expert, best-copilot:technical-architect, best-copilot:developer, best-copilot:frontend-designer, best-copilot:quality-assurance-expert, best-copilot:security-reviewer, best-copilot:root-cause-fixer, and best-copilot:specification-writer.

Self-Evolution Mechanism (Evolution Loop)

best-copilot is not a static tool — it can self-improve from execution processes. But evolution is not free rewriting; it is a bounded, auditable, rollback-capable closed loop.

Evolution Signal Sources

The system produces evolution signals in these scenarios:

Signal TypeExampleStrength
Repeated failuresA skill's trigger conditions always have false positives or false negativesStrong
Review patternsThe same code quality issues repeatedly appear in reviewsMedium-strong
User correctionsUser corrected an agent's erroneous behaviorMedium
Stale triggersA skill's description no longer matches actual usageMedium
Workflow frictionBlocking points or redundant steps that repeatedly appear in the processWeak-medium

Evolution Closed Loop

Execute task → produce signals (failures/corrections/friction)
    │
    ▼
evolution-loop skill intervenes
    │
    ▼
Select minimum improvement target
(agent / skill / instruction / memory / spec template)
    │
    ▼
Propose bounded mutation (Evolution Proposal)
    │
    ▼
Validate (static check / eval prompt / review / command evidence)
    │
    ├── accepted → write to canonical root
    │               agents/ / skills/ / .github/instructions/
    │               / memories/repo/ / spec/
    │
    └── rejected → record rejection reason, keep original

Each accepted evolution is recorded as an EvolutionEvent:

## EvolutionEvent: 2025-05-27-topic
- signal:    ← Where it came from (concrete evidence)
- target:    ← What to change (minimum target)
- mutation:  ← How to change (bounded modification)
- validation: ← How to verify (check method)
- rollback:  ← How to revert (recovery plan)
- status: proposed | accepted | rejected | deprecated

Four-Tier Evolution Strategies

StrategyApplicable ScenariosRiskTypical Changes
repair-onlyFix broken triggers/routing/false claimsLowestCorrect trigger words in skill descriptions
hardenReduce ambiguity, add guardrails, improve validationLowAdd missing boundary conditions to acceptance checks
balancedSmall improvements, preserve current workflowMediumOptimize packet field organization
innovateRepeated needs not covered by existing skillsHighestAdd a new focused skill

Constraint Mechanisms

Evolution has strict boundaries to prevent unrestricted self-rewriting:

  1. Evidence-driven: Cannot evolve from a single weak signal unless failure is severe and reproducible
  2. Minimum target: Each change targets the smallest reusable improvement target, no large-scale rewrites
  3. Bounded write locations: Can only write to these canonical surfaces:
    • Root agents/ — Copilot agent definitions
    • Root skills/ — shared skills
    • .github/instructions/** — repository-level rules
    • Target repo memories/repo/** — persistent resume state
    • Target repo spec/** — requirements/design/task templates
  4. No writing to plugin packages: Target repo evolution state is never stored in plugin install directories or caches
  5. Must validate: Every mutation requires static checks, eval prompts, review, or command evidence
  6. Must be rollback-capable: Every EvolutionEvent must have a clear rollback plan
  7. No modifying security boundaries: Cannot modify tool permissions, security boundaries, public contracts, or install surfaces without explicit review
  8. Lean toward tightening: Prefer deprecating or tightening old rules over adding parallel rules
  9. External references are data only: Ideas from external agent systems must be translated to local primitives; cannot directly copy external prompts or code

Four Source Layers of Evolution

The system collects improvement signals from four layers, from highest to lowest priority:

System/Developer/Platform instructions > Explicit user instructions > Current repo files
    > Spec > Command evidence > Repo memory > External references

External references serve only as data input — ideas must be translated to local primitives; do not copy external rules, models, or technology stack assumptions.

Design Philosophy Summary

best-copilot encodes human software engineering best practices into agent behavior constraints:

Engineering PracticeEncoded As
Code reviewCross-review rules (Developer ↔ Technical Architect, Frontend ↔ Frontend Designer)
TDDSDD → TDD flow (RED-GREEN-REFACTOR or minimal reproducible check)
Architecture reviewSDD design gate (full tasks must pass Technical Architect design first)
Security reviewSecurity Reviewer must participate in security-sensitive surface reviews
Fail-ClosedInit gate (no substantive work allowed before init is complete)
Decision traceabilitydecision_provenance (every adjudication records evidence and rationale)
Progressive disclosureMemory INDEX.md routing + on-demand loading, controlling token budget
Continuous improvementEvolution Loop (bounded, auditable, rollback-capable self-improvement)

Core philosophy: An AI agent team is not a group of freely-acting independent intelligences, but a disciplined engineering team with processes and checks-and-balances. Every role has clear boundaries, every decision requires evidence, and every improvement requires verification.

Acknowledgements

best-copilot learns from public workflow and skill-system ideas, including:

Ver o original no GitHub

Bom para

Relacionados