sefirot-loop

What is Sefirot

Sefirot is a multi-agent orchestration framework on Claude Code. Three agents (Planner / Builder / Verifier) automatically run the design→implementation→verification loop in Milestone units.

Planner: Splits tasks from design documents and assigns Waves (parallel execution units)
Builder: Implements each task in parallel within independent git worktrees (up to 8 parallel executions)
Verifier: Merges Builder branches and verifies them through tests, linting, and type checks. If verification fails, it generates a fix task and restarts the loop

All states are managed by

milestones.json

(in the task directory) and design documents (Markdown). There is no direct communication between agents; they collaborate via these files.

If an agent is unsure about a decision, it writes the question to the

questions

array in

milestones.json

and the loop pauses. This skill mediates that question to the user, reflects the answer in the design document, and restarts the loop.

Prerequisite Check

First, check if the

sefirot

CLI is installed:

bash

command -v sefirot

If it is not installed, return the following message and exit:

The
sefirot
CLI is not installed. Please install it using the following command:
bash
uv tool install git+https://github.com/agarichan/sefirot.git

Overview

Run the sefirot build loop in the background, and if there are questions from agents, confirm with the user, reflect the answers, and restart the loop.

Steps

Step 0: Confirm Target Task

Run

sefirot list --active

to check the list of incomplete tasks:

If none found: Guide the user with the following and exit:
There are no incomplete tasks. Create a design document with
/plan
and generate milestones.json with
/milestone
.
If only one found: Use it directly.
If multiple found: Present the results of
```
sefirot list --active
```
and ask the user which task to execute using the AskUserQuestion tool.

Step 1: Run Loop in Background

Use the Bash tool's

run_in_background: true

to start it in the background:

bash

sefirot loop --from-skill --task-dir <task directory identified in Step 0>

After starting, inform the user:

The sefirot loop has started in the background. You will be notified when it is completed. You can ask questions freely during execution.

Step 2: Interaction with User (During Loop Execution)

Wait for user input until the background task completion notification arrives. Respond normally if the user has questions or requests.

Typical requests:

"How's the progress?" "Tell me the status" → Read the output of the background process with TaskOutput and report the progress. Detailed logs for each agent are located under
```
.sefirot/sessions/<task name>/
```
, so check those if necessary.
Other questions → Respond normally.

Step 3: Post-Completion Processing

When the background task is completed, retrieve the output with TaskOutput. The output ends with a

[SEFIROT:ACTION]

line; follow the action instructions:

[SEFIROT:ACTION] COMPLETE
: Completed successfully. Proceed to Step 5.
[SEFIROT:ACTION] QUESTIONS_PENDING
: Questions are pending. Proceed to Step 4.
[SEFIROT:ACTION] ERROR
: Error. Report the message in the
```
[SEFIROT:MESSAGE]
```
line to the user and exit.
If
[SEFIROT:ACTION]
is not found: Unexpected crash. Report the end of the output to the user and exit.

Step 4: Process Questions

Questions from agents are stored in the

$.questions

array of

milestones.json

. milestones.json is located at

docs/tasks/<task directory>/milestones.json

Read milestones.json and retrieve the
```
questions
```
array
For each question:
- Present the question to the user in the following format:
```
[Question N/{total}] from {agent} (task: {task_id})
{question}
```
- Use the AskUserQuestion tool to get the user's answer
- Reflect the answer in the relevant design document: a. Identify the Milestone to which the corresponding task belongs from milestones.json b. Get the path of the design document from the
  plan_doc
  field of that Milestone. If there is no
  plan_doc
  field (e.g., questions from Planner), use the
  source
  field (design.md) in milestones.json c. Append the answer as "Additional Instructions" in the relevant task section (or at the end) of the design document:
  markdown
```
#### Additional Instructions (User Answer)
- Q: {original question}
- A: {user's answer}
```
After processing all questions, empty the
```
questions
```
array in milestones.json (set to
```
"questions": []
```
)

Commit the changes:

bash

git add -A && git commit -m "chore: resolve agent questions"

Return to Step 1 and run the loop in the background again.

Step 5: Completion Report

When the loop completes successfully, report the results:

Read milestones.json to understand the current state
Report the following information:
- Completed Milestones and their goals
- List of completed tasks
- Information on the next incomplete Milestone, if any
- Summary of verification results

Notes

Always run the loop in the background. Do not run it in the foreground.
Accept user input during loop execution and respond to progress checks, etc.
Only ask for the user's judgment when questions arise.
Answers to questions are persisted in the design document, so agents can reference them during re-runs.
Multiple questions may arise in one loop. Process all of them before re-running.

sefirot-loop

NPX Install

Tags

SKILL.md Content (Chinese)

What is Sefirot

Prerequisite Check

Overview

Steps

Step 0: Confirm Target Task

Step 1: Run Loop in Background

Step 2: Interaction with User (During Loop Execution)

Step 3: Post-Completion Processing

Step 4: Process Questions

Step 5: Completion Report

Notes