Capability Atlas
TreyEvreux/capability-atlas
Pesquisa inteligente governada: reutilizar vs reconstruir com evidência
Ver no GitHubSistema de inteligência de pesquisa local-first que decide o que reutilizar em vez de reconstruir, operado por agentes e governado por humanos. Cataloga ferramentas e fontes candidatas, as classifica em tiers de reuso, conecta descobertas aos objetivos do projeto e produz pacotes de decisão duráveis com rastreabilidade completa.
Instalação
npx convez-ai TreyEvreux/capability-atlas1 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
Casos de uso
- Catalogar e avaliar bibliotecas/ferramentas antes de decisões de reuso
- Manter inteligência de pesquisa durável em vez de histórico de chat efêmero
- Governar fluxos de pesquisa em equipe com revisão humana obrigatória
- Gerar pacotes de decisão com evidência, riscos e próximos passos
Veredito

Ferramenta robusta e opinada para times que precisam transformar pesquisa Ad-hoc em inteligência governada. Exige investimento em compreender o modelo operacional, mas entrega real valor em rastreabilidade e decisões reproduzíveis. MCP server bem integrado ao ecossistema Claude.
README
A tradução para o português deste README ainda está na fila.
Capability Atlas
Capability Atlas is a standalone, local-first research intelligence system for one problem: deciding what to reuse instead of rebuild — and remembering why. It records evidence about candidate tools and sources, grades them into explicit reuse tiers, connects findings to your project's goals, and produces bounded decision packets — so research becomes durable intelligence instead of evaporating into chat history.
Atlas is designed to be operated by agents and governed by a human.
Agents queue research, run the governed worker, and write review artifacts;
everything they produce stays needs_review until a human reviews or promotes
it. The human role is deliberately small: read the operator dashboard, review,
promote.
Start Here
- docs/GETTING_STARTED.md — what Atlas is for, the human operating loop, worked scenarios, and the core concepts.
- AGENTS.md — operating instructions for agents driving Atlas (CLI and MCP).
- docs/OPERATORS.md — full command reference for every subsystem.
- docs/SERVICE_RUNBOOK.md — bounded background operation and cost controls.
- docs/SECURITY.md — the security model.
What The v0.1 Build Can Do
The current build is a tested local CLI/service-control baseline:
- review existing sources before building fresh;
- classify reviewed source material into full-copy, copy-edit, adapt-pattern, reference-only, or reject tiers;
- store capabilities, claims, evidence, goals, opportunities, and decision packets;
- generate inventories for target projects;
- produce a real decision packet;
- queue research tasks;
- run a conservative worker one task at a time or in a bounded loop;
- pause/resume the worker through file-backed controls.
- mark review outcomes with an append-only audit trail.
- promote specific evidence/claims through governed checks.
- provide project/agent context and task intake through a P2-lite CLI surface.
- validate modeled plans against mechanical reality without false green results.
- expose a narrow MCP server for read-only context plus governed task intake.
- ingest explicit local documents as evidence.
- queue stale claim rechecks and approved idle research topics.
- run internal security posture audits for risky evidence, URL policy, MCP surface, source-review follow-up, and task queue exposure.
- security-gate research tasks both at intake and immediately before worker execution.
- write first-class research briefs with explicit evidence, missing proof, risk, reuse posture, quality score, and next action.
- run deterministic quality evals over reviewable intelligence outputs.
- maintain lightweight goal/proof relation records.
- run bounded service cycles with health/run logs and stop controls.
- enforce free-only cost policy by default with an append-only cost ledger.
- track scanner state and quarantine outside source candidates before review.
- inspect governed source candidates through approved web, GitHub metadata, Hugging Face Hub metadata, explicit document, and comparison adapters.
- score saved source candidates with advisory source intelligence covering license, risk, maintenance, adoption, proof gaps, reuse tier, and next action.
- inspect GitHub repository file surfaces through bounded read-only metadata: dependency manifests, tests, CI workflows, docs, and security files.
- align project ideas against saved Atlas intelligence with best-fit candidates, SWOT-style review, missing proof, and recommended next actions.
- maintain a first-pass Master Capability Registry with canonical system profiles, capability areas, ranked shortlists, context winners, freshness windows, and explicit proof/security/licensing caveats.
- seed an eight-area starter registry covering agent observability, safety testing, durable workflows, local model runtime, retrieval/vector memory, browser automation, code security scanning, and web app scaffolding.
- dedupe registry candidates into canonical provider identities such as
GitHub
owner/repoand Hugging Facetype/repo_id, while preserving multiple evidence/source refs on the same system profile. - render a human-readable Master Capability Registry overview with bottom-line recommendations, review order, top candidates, proof gaps, and use boundaries.
- constrain capability rankings with optional required/excluded match terms so broad source metadata does not become a false top recommendation.
- detect stale capability rankings and queue governed refresh tasks.
- run queued capability-ranking refreshes through the worker as review-required artifacts.
- assemble a target project capability from project reality, opportunity matrices, and ranked capability shortlists.
- discover deterministic next opportunities from saved Atlas data, including stale rankings, registry gaps, project-candidate matches, assembly proof gaps, suggested research tasks, and duplicate source candidates.
Quick Start
These commands work from a clean clone without any private project files.
Windows (PowerShell):
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
Linux/macOS:
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
Then, on any platform:
atlas seed
atlas status
atlas list source_review
atlas show decision_packet dp-defer-durable-workflow-engine-p0
atlas eval quality
atlas security public-hygiene
atlas service status
atlas report operator-dashboard --markdown
Optional Examples
These commands need a real local project, a real local document, network access,
or additional seeded registry data. Paths below use Windows form; on Linux/macOS
use forward-slash paths (for example /path/to/example-project).
atlas inventory "C:\path\to\example-project" --project-id example-project-v2
atlas ingest local-docs "C:\path\to\note.md"
atlas adapter document "C:\path\to\note.md" --project-ref Atlas
atlas adapter github https://github.com/openai/openai-python --project-ref Atlas
atlas adapter huggingface https://huggingface.co/openai/whisper-tiny --project-ref Atlas
atlas report source-intelligence --markdown
atlas registry seed-baseline --markdown
atlas registry area --id caparea-agent-observability --name "Agent Observability" --keyword tracing --keyword evals --keyword OpenTelemetry --required-term tracing --save
atlas registry rank caparea-agent-observability --project-ref example-project-v2 --save --markdown
atlas report capability-registry --markdown
atlas project assemble "agent observability and tracing for example project agent runs" --project-ref example-project-v2 --save --markdown
atlas report goal-assemblies --markdown
atlas report opportunity-discovery --project-ref example-project-v2 --markdown
atlas-mcp
Run the public project-reality proof fixture:
.\scripts\run_public_project_proof.ps1
That proof uses only generic fixture data and writes runtime output under
generated\public_project_proof_workspace.
V1 Boundary
The V1 completion line is defined in docs\V1_COMPLETION_CONTRACT.md. In short:
V1 is done when Atlas is a usable, safe, persistent research intelligence system
with governed source intake, idea alignment, explicit follow-up task queueing,
background operation, clean tests/security checks, and truth-synced docs. Larger
expansions move to the post-V1 roadmap.
The current system review and release readiness notes are tracked in
docs\CURRENT_STATE_REVIEW.md.
Open Source v0.1 Goal
The first public release target is defined in
docs\OPEN_SOURCE_V0_1_PLAN.md. Public v0.1 is the first version intended for
outside users, even if internal planning uses a different version or phase
number.
v0.1 is ready when Atlas can be cloned, installed, run, inspected, and safely extended without private local project context, tracked runtime data, secrets, user-specific paths, or unreviewed external code.
Release notes and known limits are tracked in
docs\RELEASE_NOTES_V0_1.md.
Before publishing v0.1, create a clean tree for a new public repository instead of pushing this development repository's history:
.\scripts\create_public_release_export.ps1
.\scripts\verify_public_release_export.ps1
python -m atlas.cli security public-hygiene --root generated\public_release_export --all-files
The export is written under ignored generated\public_release_export, then
installed and tested from an isolated verification environment. Use that exported
tree as the source tree for the new public repo after final review.
Background Operation
Atlas can be run as a bounded Windows Scheduled Task. The scheduled process runs one service cycle at a time, logs cost status before each cycle, and keeps the same free-only default cost boundary used by manual CLI runs.
Install or refresh the task:
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install_atlas_scheduled_task.ps1 -RepoRoot "C:\path\to\capability-atlas" -AtlasHome "C:\path\to\capability-atlas" -IntervalMinutes 5 -MaxTasksPerCycle 1
Check it:
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\status_atlas_scheduled_task.ps1
The current default task name is \CapabilityAtlas\CapabilityAtlasBackground.
Logs are written to data\logs\background_task_stdout.log and
data\logs\background_task_stderr.log.
Current Boundary
Atlas does not execute external code, install external packages, mutate target projects, or promote claims automatically. Worker outputs are unverified review artifacts until a human/governed process promotes specific claims.
Provided-link fetching blocks localhost/private-network targets, file URLs, embedded credentials, and unsafe redirects by default.
Atlas defaults to free-only cost mode. Local deterministic work is allowed, local model reasoning is permitted by policy hook, and paid API calls are blocked unless the cost policy and task budget explicitly allow them.
License
Capability Atlas is licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.
No external source files are currently pre-approved for direct copy into Atlas. Dependency adoption, copy/edit work, and source reuse must follow docs/SOURCING.md. The current v0.1 dependency and source ledger is tracked in docs/DEPENDENCY_SOURCE_LEDGER.md.