From coding-agent
coding-agent 파이프라인의 상태 전이 관리. state.json CRUD, 전이 조건 검증, failure 로깅, 중단 복구.
How this skill is triggered — by the user, by Claude, or both
Slash command
/coding-agent:state-machineThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
coding-agent 파이프라인의 상태 전이를 관리한다. 이 skill은 `Read`, `Write`, `Edit`, `Bash` 도구를 사용하여 state.json 파일을 조작한다.
coding-agent 파이프라인의 상태 전이를 관리한다. 이 skill은 Read, Write, Edit, Bash 도구를 사용하여 state.json 파일을 조작한다.
{
"ticket_id": "STABLE-1234",
"created_at": "2026-05-28T00:00:00Z",
"workspace_dir": ".coding-agent/tickets/STABLE-1234_20260528_000000",
"ticket_type": "feature",
"pipeline_variant": "full",
"requirement_source": "jira", // "jira" (default) | "local" (free-text /analyze entry)
"current_state": "TICKET_INTAKE",
"current_agent": null,
"states": {
"TICKET_INTAKE": { "status": "pending", "started_at": null, "completed_at": null, "artifacts": [], "sensitive_check": null },
"ANALYSIS": { "status": "pending", "started_at": null, "completed_at": null, "artifacts": [] },
"PLANNING": { "status": "pending", "started_at": null, "completed_at": null, "artifacts": [] },
"DESIGN": { "status": "pending", "started_at": null, "completed_at": null, "artifacts": [], "revision": 0 },
"IMPLEMENTATION":{ "status": "pending", "started_at": null, "completed_at": null, "branch": null, "plan_progress": null, "commits": [] },
"EVALUATION": { "status": "pending", "started_at": null, "completed_at": null, "results": { "unit_test": null, "lint": null, "security": null, "chainbench": null }, "report_path": null },
"COMPLETION": { "status": "pending", "pr_url": null, "merged_at": null, "merge_commit": null }
},
"failure_log": [],
"failure_summary": { "total_failures": 0, "by_state": {}, "by_type": {}, "recurring_patterns": [] },
"config": {
"max_design_revisions": 3,
"max_eval_cycles": 3,
"impl_model": "sonnet-4.6",
"planning_model": "opus-4.7",
"autonomy": {
"mode": "interactive", // "interactive" (default) | "auto"
"on_blocked": "halt", // "halt" (default) | "escalate" — what to do at BLOCKED/limits
"auto_merge": false // false → PR 생성까지만 자율, merge/push/tag 는 게이트 유지(권장)
}
}
}
{
"total_steps": 5,
"steps": [
{
"step_id": 1,
"description": "...",
"status": "completed",
"commits": ["a1b2c3d"],
"started_at": "...",
"completed_at": "...",
"last_checkpoint": null
}
]
}
{
"at": "2026-05-28T01:45:00Z",
"reason": "token_limit",
"work_in_progress": "함수 구현 70%. edge case 처리 남음",
"uncommitted_files": ["consensus/wbft/finalize.go"]
}
{
"id": "fail-001",
"occurred_at": "2026-05-28T01:23:45Z",
"state": "EVALUATION",
"agent": "evaluator",
"step": "unit_test",
"attempted_action": {
"description": "...",
"command": "go test ./consensus/wbft/...",
"related_plan_step": "plan.md#step-3",
"related_design": "design-v2.md#section-2.1",
"modified_files": ["..."]
},
"expected_outcome": "TestFinalize PASS",
"actual_outcome": {
"type": "test_failure",
"summary": "panic: nil pointer",
"details": "...",
"exit_code": 2,
"log_file": "logs/eval-fail-001.log"
},
"agent_analysis": {
"root_cause_hypothesis": "...",
"confidence": "mid",
"suggested_fix": "..."
},
"resolution": {
"action": "retry_cycle",
"transitioned_to": "ANALYSIS",
"retry_count": 1
}
}
역할: state.json을 새로 생성하고 TICKET_INTAKE 상태로 초기화.
입력:
ticket_id (string): 예 "STABLE-1234" (free-text 진입 시 "LOCAL-{timestamp}")ticket_type (string): "feature" | "bugfix" | "code_review" | "release"workspace_dir (string): 작업 폴더 절대 경로pipeline_variant (string): "full" | "review_only" | "release"requirement_source (string, optional): "jira" (기본) | "local". /coding-agent:analyze
자유 텍스트 진입은 "local". orchestrator가 이 값으로 Jira pre-flight/종료 동기화를 분기한다.절차:
현재 UTC 시각을 ISO 8601 포맷으로 획득.
date -u +"%Y-%m-%dT%H:%M:%SZ"
위의 "데이터 모델" 섹션의 state.json 기본 스키마를 사용하여 객체 구성:
ticket_id, workspace_dir, ticket_type, pipeline_variant를 입력값으로 채움requirement_source를 입력값으로 채움 (미지정 시 "jira")config.autonomy를 requirement_source로부터 유도:
"local" → { mode: "auto", on_blocked: "escalate", auto_merge: false }"jira" → { mode: "interactive", on_blocked: "halt", auto_merge: false }created_at을 현재 시각으로 설정current_state는 "TICKET_INTAKE"states[*].status는 "pending"failure_log은 빈 배열, failure_summary는 기본값Write 도구로 {workspace_dir}/state.json 생성.
출력: 생성된 state.json의 절대 경로 + 초기 객체.
역할: 현재 상태와 진행률을 조회.
입력:
workspace_dir (string): 작업 폴더 경로절차:
Read 도구로 {workspace_dir}/state.json 로드.ticket_id, current_state, current_agentstates[current_state]의 전체 객체plan_progress 요약 (총 step 수, 완료 step 수, 현재 step의 description)failure_summary 요약출력: 위 정보를 담은 객체.
역할: 전이 조건을 검증하고, 충족 시 상태를 업데이트.
입력:
workspace_dir (string)from_state (string): 현재 상태to_state (string): 전이 목표 상태artifacts (array of string, optional): 새로 생성된 아티팩트 파일 경로절차:
Read 도구로 state.json 로드.
현재 상태 일치 확인:
{ "error": "STATE_MISMATCH", "expected": from_state, "actual": state.current_state } 반환전이 조건 검증 (from_state → to_state 별):
TICKET_INTAKE → ANALYSIS:
Bash: test -f {workspace_dir}/ticket.json && echo OK → OK 인지 확인ANALYSIS → PLANNING:
Bash: test -f {workspace_dir}/analysis.md && test -f {workspace_dir}/related-code.json && echo OKresults 배열이 존재하고 비어있지 않은지 확인PLANNING → DESIGN:
Bash: test -f {workspace_dir}/plan.md && echo OKgrep -c "^## Step" {workspace_dir}/plan.md)DESIGN → IMPLEMENTATION:
ls {workspace_dir}/design-v*.md)IMPLEMENTATION → EVALUATION:
Bash: cd {workspace_dir 의 git 레포 루트} && git status --porcelain → 빈 출력 (uncommitted 없음)EVALUATION → COMPLETION:
EVALUATION → ANALYSIS (fail cycle):
* → BLOCKED:
검증 실패 시:
{
"error": "TRANSITION_BLOCKED",
"missing": ["analysis.md not found", "related-code.json is empty"],
"from": "ANALYSIS",
"to": "PLANNING"
}
검증 성공 시 state.json 업데이트:
states[from_state].status = "completed"states[from_state].completed_at = now()states[from_state].artifacts.push(...artifacts) (중복 제거)states[to_state].status = "in_progress"states[to_state].started_at = now()current_state = to_stateWrite 도구로 state.json 저장출력: 성공 시 { "ok": true, "new_state": to_state }, 실패 시 위 에러 객체.
역할: IMPLEMENTATION 단계의 step 진행 상태를 업데이트.
입력:
workspace_dir (string)step_id (integer): plan_progress.steps 의 step_idstatus (string): "pending" | "in_progress" | "completed" | "failed"checkpoint (object, optional): last_checkpoint 스키마. null이면 삭제.commits (array of string, optional): 추가할 commit hash 목록절차:
Read 도구로 state.json 로드.
states.IMPLEMENTATION.plan_progress.steps 에서 step_id 매칭되는 항목 찾기. 미존재 시 에러.
매칭된 step 객체 업데이트:
step.status = statusstates.IMPLEMENTATION.commits 전체 목록에도 commits 추가.
Write 도구로 state.json 저장.
출력: { "ok": true, "step_id": step_id, "new_status": status }
역할: failure_log에 실패 기록을 추가하고 failure_summary를 자동 업데이트.
입력:
workspace_dir (string)failure_entry (object): 위 "데이터 모델"의 failure_entry 스키마절차:
Read 도구로 state.json 로드.
failure_entry.id 자동 부여 (입력에 없으면):
id = "fail-" + zero_pad(failure_log.length + 1, 3) (예: "fail-001")failure_entry.occurred_at 자동 부여 (입력에 없으면): 현재 시각.
failure_log.push(failure_entry)
failure_summary 업데이트:
failure_summary.total_failures += 1failure_summary.by_state[failure_entry.state] = (existing || 0) + 1failure_summary.by_type[failure_entry.actual_outcome.type] = (existing || 0) + 1recurring_patterns 갱신:
failure_entry.actual_outcome.summary 에서 핵심 토큰 추출
pattern.occurrences += 1, pattern.failure_ids.push(failure_entry.id){ "pattern": "<key>", "occurrences": <count>, "failure_ids": [...] }
Write 도구로 state.json 저장.
출력: { "ok": true, "failure_id": failure_entry.id }
역할: 중단된 작업의 재개 지점을 반환.
입력:
workspace_dir (string)절차:
Read 도구로 state.json 로드.
상태별 재개 지점 결정:
current_state == "IMPLEMENTATION" (가장 정교한 복구):
plan_progress.steps 에서 첫 번째 non-completed step 탐색{
"state": "IMPLEMENTATION",
"step": { "step_id": N, "description": "...", "status": "in_progress" },
"checkpoint": { "at": "...", "reason": "...", "work_in_progress": "...", "uncommitted_files": [...] }
}
Bash: cd {repo_root} && git diff --name-only 로 uncommitted 파일 확인current_state == "ANALYSIS" / "PLANNING" / "DESIGN" (RI-02 대응):
{
"state": "<current_state>",
"sub_status": "fresh" | "partial" | "review_pending",
"existing_artifacts": [...],
"recommendation": "처음부터 재실행" | "기존 아티팩트 활용하여 이어서"
}
current_state == "EVALUATION":
{ "state": "EVALUATION", "last_stage_completed": "lint", "next_stage": "security" }
current_state == "TICKET_INTAKE" / "COMPLETION":
{ "state": current_state, "step": null, "checkpoint": null }current_state == "BLOCKED":
{
"state": "BLOCKED",
"block_reason": "...",
"failure_summary": {...},
"recommendation": "유저 개입 필요"
}
출력: 위의 상태별 재개 지점 객체.
| From → To | 핵심 조건 |
|---|---|
| TICKET_INTAKE → ANALYSIS | ticket.json 존재 + sensitive_check CLEAN/REDACTED |
| ANALYSIS → PLANNING | analysis.md (>200자) + related-code.json (results 비어있지 않음) |
| PLANNING → DESIGN | plan.md 존재 + ## Step 헤더 ≥1 |
| DESIGN → IMPLEMENTATION | design-v{N}.md 존재 + revision ≤ max_design_revisions |
| IMPLEMENTATION → EVALUATION | 모든 step completed + commits 존재 + uncommitted 없음 |
| EVALUATION → COMPLETION | 모든 test result PASS/WARN |
| EVALUATION → ANALYSIS | 하나 이상 FAIL + cycles < max_eval_cycles |
| * → BLOCKED | cycles ≥ max_eval_cycles 또는 design revision ≥ max |
1. init_state("STABLE-1234", "feature", ".coding-agent/tickets/STABLE-1234_20260528_120000", "full")
2. ticket.json 작성
3. transition(workspace_dir, "TICKET_INTAKE", "ANALYSIS", ["ticket.json"])
1. get_resume_point(workspace_dir)
→ { state: "IMPLEMENTATION", step: {step_id: 2, ...}, checkpoint: {...} }
2. checkpoint.work_in_progress 를 Implementer agent 에 전달하여 재개
3. step 완료 시: update_step_progress(workspace_dir, 2, "completed", null, ["e4f5g6h"])
1. test 실패 발생
2. log_failure(workspace_dir, {
state: "EVALUATION",
agent: "evaluator",
step: "unit_test",
attempted_action: {...},
actual_outcome: { type: "test_failure", summary: "...", ... },
agent_analysis: {...},
resolution: { action: "retry_cycle", transitioned_to: "ANALYSIS", retry_count: 1 }
})
3. transition(workspace_dir, "EVALUATION", "ANALYSIS")
Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub 0xmhha/coding-agent --plugin coding-agent