convez.ai
AgenteProdutividadeIntermediário
Tianyang-human

T-Kiro Agent

Tianyang-human/t-kiro-agent

Workflow spec-driven: requisitos → design → tarefas → execução com gates de aprovação

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent spec-driven para Claude Code e Cursor que guia o desenvolvimento de features através de fases estruturadas: requisitos, design, tarefas e execução. Cada fase gera artefatos em markdown e requer aprovação explícita antes de avançar, evitando saltos diretos para implementação sem fundamentação.

Instalação

$npx convez-ai Tianyang-human/t-kiro-agent

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

Casos de uso

  • Planejar features complexas com validação de requisitos antes de codificar
  • Documentar decisões arquiteturais e alternativas consideradas durante design
  • Quebrar features em tarefas discretas e testáveis antes da implementação
  • Evitar retrabalho causado por requisitos mal compreendidos ou design inadequado

Veredito

Ferramenta sólida para disciplinar o desenvolvimento com agents, forçando pausas deliberadas entre fases. Melhor para equipes que valorizam especificação antes de código e documentação durável fora do repositório.

README

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

t-kiro-agent

A spec-driven development workflow for Claude Code, Cursor, and Codex. It walks a feature from requirements through design, task breakdown, and implementation — each stage gated by explicit user approval.

Inspired by Amazon Kiro's spec-driven approach.

Why

Coding agents often jump straight to implementation and miss important requirements, architectural decisions, or edge cases. This workflow forces a disciplined pause between stages:

  1. Requirements — what are we building, for whom, and what's out of scope?
  2. Design — how will it work technically? What alternatives were considered?
  3. Tasks — what are the discrete, testable chunks of work?
  4. Execution — implement one main task at a time with verification gates.

Each stage produces a durable markdown artifact outside the repository (under ~/.kiro/), and each stage requires approval intent from the user before automatically moving to the next phase.

Workflow

The recommended entry point is the unified router:

/kiro <feature>                →  routes to the right phase based on `.status`
/kiro <feature> --redo <phase> →  re-run a previously approved phase

Under the hood, /kiro dispatches to one of four phase agents in Claude/Cursor. In Codex, $kiro routes to equivalent Codex skills and optional custom agents:

requirements  →  requirements-agent  →  ~/.kiro/<repo>/<feature>/requirements.md  →  APPROVE
design        →  design-agent        →  ~/.kiro/<repo>/<feature>/design.md        →  APPROVE
tasks         →  tasks-agent         →  ~/.kiro/<repo>/<feature>/tasks.md         →  APPROVE
execute       →  execution-agent     →  implements one main task at a time

Each phase is also exposed as a standalone slash command (/requirements, /design, /tasks, /execute) if you prefer to drive phases manually. In the normal routed flow, approval automatically starts the next phase.

Specs live under ~/.kiro/<repo-name>/<feature-name>/ (outside the repository). They are intentionally not committed to the repo — they are for the developer's benefit during feature planning, not part of the codebase history.

A small .status file in the same directory tracks the current phase and approval state, so re-running /kiro <feature> resumes mid-flight rather than starting over.

Install

Claude Code, Cursor, and Codex

Claude Code and Cursor read ~/.claude/agents/ and ~/.claude/commands/. Codex reads skills from ~/.agents/skills/ and custom agents from ~/.codex/agents/.

git clone https://github.com/Tianyang-human/t-kiro-agent.git
cd t-kiro-agent
./install.sh

Then fully restart Claude Code, reload the Cursor window (Cmd+Shift+P → Developer: Reload Window), or restart Codex.

Manual install

Copy the four agent files to ~/.claude/agents/ and the five command files (requirements.md, design.md, tasks.md, execute.md, kiro.md) to ~/.claude/commands/.

For Codex, copy:

  • codex/skills/* to ~/.agents/skills/
  • codex/agents/*.toml to ~/.codex/agents/

Usage

From within any git repository:

/kiro <feature-name>
# Routes to the right phase based on ~/.kiro/<repo>/<feature>/.status:
#   - no .status        → starts requirements
#   - draft_written     → re-displays the existing draft and re-prompts for APPROVE
#   - approved          → automatically advances to the next phase
#   - approved + edits  → warns about staleness and re-prompts for APPROVE

To re-run a previously approved phase:

/kiro <feature-name> --redo <phase>
# <phase> is one of: requirements | design | tasks | execute

<feature-name> is a short slug (e.g., user-auth, bulk-export). The same slug is used across all four stages.

For Codex, invoke the equivalent skill:

$kiro <feature-name>
$kiro <feature-name> --redo <phase>

Agents

Claude/Cursor AgentCodex SkillWrites toPurpose
requirements-agentkiro-requirements~/.kiro/<repo>/<feature>/requirements.mdGather user stories, edge cases, constraints, success criteria, out-of-scope items
design-agentkiro-design~/.kiro/<repo>/<feature>/design.mdProduce component breakdown, data models, API contracts, mermaid diagrams, alternatives considered
tasks-agentkiro-tasks~/.kiro/<repo>/<feature>/tasks.mdBreak design into hierarchical main tasks and sub-tasks with acceptance criteria
execution-agentkiro-executesource files in the repoImplement one main task at a time; run tests + compile after each; pause for user confirmation

Guardrails

  • Agents may only write to ~/.kiro/ except for execution-agent, which edits source files
  • Agents do not git add or git commit anything unless explicitly asked
  • Each stage requires clear approval intent before progressing
  • Approval automatically starts the next phase when one exists
  • Design decision points stay under 50 lines while total design length scales with feature complexity
  • Every generated main task ends with a final test step that must pass before completion
  • execution-agent runs package-level tests and compile after every main task; failing verification blocks completion
  • Before PR handoff, execution-agent runs three staff-level review rounds and reports the top five comments per round

Workspace conventions

For Claude/Cursor, if AGENT.md and/or CLAUDE.md exist in the repository, every agent reads them at startup and binds the resulting coding-style and testing rules to its output. When both files exist and disagree, CLAUDE.md wins.

For Codex, prefer AGENTS.md for repository instructions. The Codex skills also read AGENT.md and CLAUDE.md as compatibility files when present.

Superpower skills

Agents auto-invoke relevant obra/superpowers skills where they add value:

AgentSkills
requirements-agentbrainstorming, writing-plans
design-agentbrainstorming
tasks-agentwriting-plans
execution-agenttest-driven-development, verification-before-completion, systematic-debugging, finishing-a-development-branch

If the obra/superpowers plugin isn't installed, agents log an inline note and continue without the skill.

Uninstall

./uninstall.sh

Removes the Claude/Cursor agents and commands from ~/.claude/, plus Codex skills and custom agents from ~/.agents/skills/ and ~/.codex/agents/. Your ~/.kiro/ specs are preserved.

Customizing for your own workflow

The path ~/.kiro/ is a convention. If you prefer in-repo specs (e.g., docs/specs/), edit the Claude/Cursor files and Codex skills to reference your preferred location. Be consistent across both — agents, commands, and skills must agree.

Repository layout

t-kiro-agent/
├── subagents/     # Claude Code / Cursor subagent definitions (installed into ~/.claude/agents/)
├── commands/      # Slash command definitions (installed into ~/.claude/commands/)
├── codex/
│   ├── skills/    # Codex skills (installed into ~/.agents/skills/)
│   └── agents/    # Codex custom agents (installed into ~/.codex/agents/)
├── install.sh
├── uninstall.sh
└── README.md

The directory is named subagents/ rather than agents/ because agents/ is a restricted path under Instacart's GitHub push protection. At install time, these files are placed into ~/.claude/agents/.

Development

Edit the files in subagents/, commands/, or codex/, then re-run ./install.sh to apply.

Ver o original no GitHub

Bom para

Relacionados