convez.ai
SkillDesenvolvimento WebAvançado
handharr-labs

CipherPol — Toolkit Agnóstico para Clean Architecture

handharr-labs/software-dev-agentic

Agentes Claude para arquitetura limpa em múltiplas plataformas

Ver no GitHub
InicialPluginScore · de 0 a 100

Conjunto de agentes, skills e conhecimento arquitetural para projetos multiplatforma (Flutter, iOS, Android, Web) baseados em Clean Architecture. Distribui personas coerentes (developer, debugger, tracker, auditor, qa) e um servidor MCP com base de conhecimento específica por plataforma via ChromaDB.

Instalação

$npx convez-ai handharr-labs/software-dev-agentic

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
1
Forks
0
Acompanhando
0
Saúde
37%
Último commit
há 4 meses
Versão
—
Issues abertas
2
Contribuidores
1

Casos de uso

  • Gerar código consistente com Clean Architecture em Flutter/iOS/Android/Web
  • Debugar e auditar desvios arquiteturais em projetos multiplatforma
  • Rastrear feature inventory e endpoints da API por projeto
  • Acelerar onboarding de desenvolvedores com knowledge base contextualizada

Veredito

Solução técnica sólida para equipes que trabalham com Clean Architecture em múltiplas plataformas. Requer configuração inicial de MCP server e marketplace, mas automatiza resolução de plataforma e consultas ao repositório de conhecimento. Recomendado para projetos maiores com padronização arquitetural rigorosa.

README

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

CipherPol

Claude Code toolkit for Clean Architecture projects

A multi-platform agentic toolkit — agents, skills, and architecture knowledge for Clean Architecture projects. Distributed as Claude Code plugins.

Platforms: Flutter · iOS (Swift/UIKit) · Android (Kotlin) · Web (Next.js)


How it works

Agents are organized into personas — coherent workflow groups (developer, debugger, tracker, auditor, qa). All personas ship in a single cipherpol-aegis plugin.

Platform-specific knowledge lives in the KMS (ChromaDB-backed MCP server, cipherpol-8). Agents query kms_list → kms_query at runtime, scoped to the project's platform. Project-specific context (feature inventory, deviations, API endpoints) is seeded per project via /kms-seed.

Platform is declared once in settings.local.json (CIPHERPOL_PLATFORM) and cross-checked against CLAUDE.md. Agents resolve it automatically — no per-platform plugin needed.


Setup

1. Register marketplace (once per machine)

CLI:

claude plugin marketplace add hndhr/software-dev-agentic

Manual — add to ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "cipherpol": {
      "source": { "source": "github", "repo": "hndhr/software-dev-agentic" }
    }
  }
}

Migrating from sda? Remove the old sda entry from extraKnownMarketplaces if present.

2. Enable plugins and configure env

Written by the installer. Edit manually to override any value. Use .claude/settings.json to share with the team or .claude/settings.local.json to keep it personal (gitignored).

{
  "enabledPlugins": {
    "cipherpol-aegis@cipherpol": true,
    "cipherpol-8@cipherpol": true
  },
  "env": {
    "CIPHERPOL_PLATFORM": "flutter",
    "CIPHERPOL_PROJECT": "talenta"
  },
  "skillListingBudgetFraction": 0.03
}
KeyValuesPurpose
CIPHERPOL_PLATFORMflutter · ios · android · webKMS scope for platform knowledge queries
CIPHERPOL_PROJECTtalenta · jurnal · qontak-crm · qontak-chat · any stringKMS scope for project-specific knowledge
skillListingBudgetFraction0.03 (recommended)Fraction of context budget reserved for skill listing

CIPHERPOL_PLATFORM and CIPHERPOL_PROJECT are read by every agent via detect-platform before making KMS calls. If both env and CLAUDE.md are set and disagree, the env var takes precedence and /cipherpol-status will flag the conflict.

3. Wire the KMS MCP server (user scope, once per machine)

cipherpol-8 runs as an MCP server. Register it at user scope in ~/.claude.json under mcpServers:

"cp8": {
  "type": "stdio",
  "command": "bash",
  "args": [
    "-c",
    "latest=$(ls \"$HOME/.claude/plugins/cache/cipherpol/cipherpol-8\" 2>/dev/null | sort -t. -k1,1n -k2,2n -k3,3n | tail -1) && exec bash \"$HOME/.claude/plugins/cache/cipherpol/cipherpol-8/$latest/kms/server.sh\""
  ],
  "env": {}
}
EnvDefaultPurpose
CP8_ENABLE_LOGGINGfalseEnable MCP server request/response logging
CP8_LOG_MAX_MB10Max log file size in MB before rotation

Set these in ~/.claude/settings.json under env to apply globally (see Step 3).

Migrating from kms? Remove any kms entry from .mcp.json or ~/.claude.json and replace with the cp8 entry above.

4. Activate

Run /reload-plugins in Claude Code, then verify with /cipherpol-status.

5. Seed project knowledge

The plugin ships with platform-level patterns pre-seeded. Add your project's specific knowledge:

/kms-seed

Or extract directly from the codebase:

/kms-extract-codebase

Updates

/plugin marketplace update cipherpol

What's included

Agents — by persona

developer — feature construction across CLEAN layers

AgentPurpose
developer-feature-strategistBrain of the developer persona — decides which layer planners to spawn, synthesizes plan.md + context.md
developer-feature-workerExecute an approved feature plan layer by layer
developer-backend-workerBuild Domain + Data layers directly
developer-ui-workerCreate or update screens and components bound to an existing StateHolder
developer-test-workerRoute test generation to the correct layer procedure
developer-domain-plannerDiscover Domain layer — entities, use cases, repository interfaces. Read-only.
developer-data-plannerDiscover Data layer — DTOs, mappers, datasources, repository impls. Read-only.
developer-pres-plannerDiscover Presentation layer — StateHolders, screens, components. Read-only.
developer-app-plannerDiscover App layer — DI, routing, module, analytics, feature flags. Read-only.
developer-groom-strategistGroom a Jira ticket against the codebase
developer-rfc-writerWrite RFC + breakdown from converged plan
developer-figma-workerExtract Figma design context and write alignment files

debugger — debugging and root cause analysis

AgentPurpose
debugger-strategistCoordinate debug investigation — static analysis then runtime instrumentation
debugger-workerTrace a runtime error through CLEAN layers to its root cause
debugger-log-workerAdd or remove debug log statements for a specific investigation

tracker — issue and ticket lifecycle

AgentPurpose
tracker-issue-workerCreate or pick up a GitHub issue, open the feature branch, update backlog
tracker-jira-ticket-workerCreate Jira tickets under an epic from a platform breakdown list

auditor — architecture compliance

AgentPurpose
auditor-arch-review-workerAudit code for CLEAN Architecture violations — layer boundaries, entity purity, naming conventions

qa — test case and automation generation

AgentPurpose
qa-testcase-workerGenerate mobile UI test cases from Jira tickets, PRDs, or Figma designs
qa-automation-workerTranslate test case CSVs into Maestro YAML automation scripts

Skills — by persona

developer

SkillPurpose
/developer-build-featureBuild or resume a feature — plan-first or build-directly
/developer-plan-featureRun convergence planning loop, show approval, then execute
/developer-build-from-ticketOne-shot build from a Jira ticket — non-interactive
/developer-backendBuild Domain + Data layers only
/developer-rfcWrite RFC + breakdown from a Jira epic
/developer-groom-ticketGroom a locally fetched Jira ticket against the codebase
/developer-clear-runsRemove stale run state from .claude/agentic-state/runs/

debugger

SkillPurpose
/debugger-debugTrigger debug investigation — static analysis then optional instrumentation

tracker

SkillPurpose
/tracker-jira-ticketCreate Jira tickets under an epic from a platform breakdown list
/tracker-issueCreate or pick up a GitHub issue, create branch, update backlog
/tracker-adjust-ticketUpdate the Session Adjustment section of a locally fetched ticket

auditor

SkillPurpose
/auditor-arch-reviewAudit code for CLEAN Architecture violations

qa

SkillPurpose
/qa-generate-testcaseGenerate mobile UI test cases from Jira, Confluence, or Figma
/qa-generate-automationGenerate Maestro YAML automation scripts from test case CSVs

utility

SkillPurpose
/installer-doctorAudit the plugin setup — plugin, KMS, CLAUDE.md, settings, gh auth
/cipherpol-statusFull CipherPol health check — platform, project, plugin versions, KMS connectivity, knowledge coverage
/kms-seedSeed ChromaDB from registered knowledge sources
/kms-extract-codebaseScan a local project repo and extract project-reality docs into KMS
/agentic-perf-reviewScore a Claude session on D1–D7 dimensions, write a report
/releaseCut a new release — bumps VERSION, prepends CHANGELOG, commits, tags

Recommended Workflows

Workflow 1 — Tracker Persona

1a — Create Jira Tickets from PRD

What you need: Atlassian MCP authenticated · Jira epic key · platform breakdown list

/tracker-jira-ticket

epic_key: PROJ-1234
cloud_id: yourcompany.atlassian.net
project_key: PROJ
prd_source: https://yourcompany.atlassian.net/wiki/spaces/ENG/pages/123456789/Feature+PRD

breakdown:
- [ADR] [UI+API] Show location marker on map: 2 days
- [iOS] [UI+API] Show location marker on map: 2 days

1b — Update Ticket Progress

Session update:

Work items completed:
- Migrated GetLocationListUseCase to new datasource pattern

/tracker-adjust-ticket path/to/TICKET-123.md

Workflow 2 — Developer Persona: Groom then build

Step 1 — Fetch the ticket locally via Atlassian MCP.

Step 2 — Groom the ticket

We have some things to address:

1. Cache mechanism in Connection.swift — keep, improve, or replace?
2. Some APIs still use the old pattern — need migration

/developer-groom-ticket path/to/TICKET-123.md

Step 3 — Start a fresh session (/clear or new Claude Code session).

Step 4 — Plan and build

Let's work on the work items in this ticket.

/developer-plan-feature path/to/TICKET-123.md

Step 5 — Update ticket progress

/tracker-adjust-ticket path/to/TICKET-123.md

Architecture

All agents enforce Clean Architecture:

Presentation  →  Domain  ←  Data
  • Domain — pure business logic, zero framework imports. Entities, use cases, repository interfaces.
  • Data — implements domain interfaces. Remote/DB data sources, mappers, repository implementations.
  • Presentation — StateHolder (ViewModel / BLoC / Presenter), UI screens, navigation. Depends only on domain.
PlatformLanguageState management
FlutterDartBLoC / Cubit
iOSSwiftViewModel + Coordinator
AndroidKotlinPresenter
WebTypeScriptCustom hooks

Platform pattern knowledge lives in ChromaDB (primary via KMS MCP). Agents always query with platform=$CIPHERPOL_PLATFORM.


Repo structure

lib/
  core/
    agents/       ← all persona agents (flat in plugin)
    skills/       ← all skills (flat in plugin)
  plugins/
    cipherpol-aegis/     ← build.config.json + build.sh
    cipherpol-8/      ← build.config.json + build.sh
kms/              ← ChromaDB MCP server source
scripts/
  build-plugin.sh      ← discovers lib/plugins/*/build.sh and runs them
  install-plugin.sh    ← downstream project setup
  plugin-lib.sh        ← shared build helpers
cipherpol.json   ← canonical platform registry (id → kms_id + detection markers)

Design docs


.gitignore recommendations

.claude/agentic-state/
.claude/settings.local.json
Ver o original no GitHub

Bom para

Relacionados