sefirot-loop

• 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

milestones.json

questions

milestones.json

sefirot

command -v sefirot

The

sefirot

CLI is not installed. Please install it using the following command:

bash

uv tool install git+https://github.com/agarichan/sefirot.git

sefirot list --active

• 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.

run_in_background: true

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

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

• "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.

[SEFIROT:ACTION]

• [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.

$.questions

milestones.json

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

1. Read milestones.json and retrieve the

   questions

   array
2. 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}

3. After processing all questions, empty the

   questions

   array in milestones.json (set to

   "questions": []

   )
4. Commit the changes:
   bash

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

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

1. Read milestones.json to understand the current state
2. 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

• 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.