القائمة
Run and monitor samocode autonomous sessions on projects. Use when user says "run samocode" or wants to continue a samocode session.
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/Yuvasee/samocode --skill samocode-runيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
عرض SKILL.md
استنادا إلى تصنيف SOC المهني
Execute implementation tasks with different approaches (single, dual-agent, plan-based).
Code quality analysis through cleanup analysis, multi-perspective reviews, and explicit finding decisions.
Interactive task definition with Q&A and documentation.
| name | samocode-run |
| description | Run and monitor samocode autonomous sessions on projects. Use when user says "run samocode" or wants to continue a samocode session. |
Runs the samocode autonomous orchestrator on a project session and monitors its progress.
When user asks to "run samocode" or "continue samocode", you MUST use this skill.
DO NOT:
_overview.md and decide what phase to run_signal.json yourselfThe Python worker (main.py) handles ALL of this. Your job is to START the worker and MONITOR its output.
Use this skill when user says:
/samocode-implementSamocode is an autonomous session orchestrator that runs the configured AI CLI provider in a loop to complete complex tasks. It:
_overview.mdFor workflow details and phase definitions, see ~/samocode/CLAUDE.md.
There's no strict "samocode session" - just sessions. Any session can be worked on:
This flexibility is intentional. Use samocode for repetitive/long-running phases, work manually when human judgment is needed.
Only when user explicitly asks for samocode (see Trigger Phrases above).
Do NOT assume samocode should run just because a session exists.
Arguments: $ARGUMENTS (session name or project path with session name)
Find .samocode config:
.samocode file in current working dir or project path.samocode file (e.g., ~/project/.samocode).samocode file is missing: ERROR and ask user to create itDetermine session name:
$ARGUMENTS is a session name (e.g., "my-task"), use it directly$ARGUMENTS includes a path, extract session name from itCheck session state (if exists):
_overview.md Status section/samocode-implement equivalent:
Phase: planning and the session is waiting for plan approval (Blocked: waiting_human, Next: Await plan approval, or _signal.json has waiting_for: plan_approval / "for": "plan_approval"), approve the gate before starting samocode:
Phase: implementationBlocked: noLast Action: Plan approved for implementationNext: Execute first implementation phase- [MM-DD HH:MM] Plan approved for implementation via samocode-runPhase: done:
_overview.md:
Phase: investigationLast Action: Resuming session for: [user's goal]Next: Investigate approach for [user's goal]When samocode signals waiting:
Auto-approve/answer ONLY if user explicitly requested it (e.g., "run samocode and approve", "accept suggestions", "auto-approve"). Otherwise, report the waiting state and wait for user decision.
For waiting_for: plan_approval:
_overview.md (NOT _signal.json):
Phase: implementationBlocked: noLast Action: Plan approved by humanFor waiting_for: qa_answers:
_qa.md with answersCRITICAL: Update _overview.md, not _signal.json
The orchestrator reads phase from _overview.md. Writing to _signal.json alone will cause loops.
.samocode FileEvery project using samocode MUST have a .samocode file in its root:
MAIN_REPO=~/path/to/main/repo
WORKTREES=~/path/to/worktrees/
SESSIONS=~/path/to/_sessions/
All three keys are REQUIRED:
MAIN_REPO: The main working directory (where the child agent runs)SESSIONS: Where samocode session folders are storedWORKTREES: Where git worktrees are createdSessions are stored in SESSIONS dir (from .samocode file), NOT nested inside projects:
[SESSIONS_DIR]/
└── [YY-MM-DD]-[session-name]/ # Session folder (e.g., 26-01-15-pyright-ci)
├── _overview.md # Main session state
├── _signal.json # Control signal
├── _qa.md # Q&A when waiting for human input
├── _logs/ # Agent iteration logs (JSONL)
│ └── [MM-DD-HHMM]-[NNN]-[phase].jsonl
├── [MM-DD-HH:mm]-plan-*.md # Implementation plans
├── [MM-DD-HH:mm]-dive-*.md # Investigation reports
└── [MM-DD-HH:mm]-*.md # Other artifacts
## Status
Phase: [investigation|planning|implementation|testing|quality|done]
Iteration: N
Blocked: [yes/no]
Last Action: [what happened]
Next: [what to do next]
## Flow Log
- [NNN @ MM-DD HH:MM] Event description -> optional-file.md
.samocode file in project root with SESSIONS, WORKTREES, MAIN_REPO~/samocode/.env has TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_IDCLAUDE_TIMEOUT or CODEX_TIMEOUT) if iterations need moreIf samocode exhibits bugs or weird behavior (loops, wrong decisions, missing steps, etc.):
Analyze the issue:
_overview.md to see what went wrongSuggest fixes - DO NOT auto-implement:
Samocode source locations:
~/samocode/main.py, ~/samocode/worker/~/samocode/workflow.md~/samocode/skills/*/SKILL.md~/samocode/commands/*.mdCommon fix patterns:
IMPORTANT: Always propose fixes and wait for user approval. Samocode is critical infrastructure - no cowboy coding.
User: "Run samocode on the hvac project"
→ Find ~/code/hvac-voice-agent/.samocode file
→ Determine session name from context (e.g., "voice-agent")
→ Run: python main.py --config ~/code/hvac-voice-agent/.samocode --session voice-agent
→ Monitor iterations, report progress
User: "Continue the samocode session"
→ Find session name from context or ask user
→ Find .samocode file path
→ Run: python main.py --config [CONFIG_PATH] --session [SESSION_NAME]
→ Monitor iterations, report progress
Remember: You run python main.py, the Python worker runs the configured provider (Claude or Codex). You do NOT run phase agents yourself.
- [MM-DD HH:MM] Resuming: [user's goal]Blocked: yes or blocked:
Start samocode:
cd ~/samocode && python main.py \
--config [PATH_TO_.SAMOCODE] \
--session [SESSION_NAME] 2>&1
Optional: Add --timeout SECONDS for per-iteration time limit (default: 1800s = 30 min).
Each child agent iteration is killed if it exceeds this. Increase for complex phases:
python main.py --config ... --session ... --timeout 3600 # 1 hour per iteration
Do NOT wrap with bash timeout - The orchestrator manages its own timeouts via --timeout.
External timeouts can kill iterations mid-work and corrupt session state.
Run this in background using run_in_background: true
Avoid reading background task output directly. The samocode worker output includes full
Agent CLI logs which are large (100KB+ per iteration). Monitor progress via _overview.md
and other session files instead.
If debugging requires checking task output (e.g., investigating a crash):
grep to search for specific errors or patterns firsttail -n 2 or tail -n 5 max - each line can be huge (full JSON)Read with offset and limit to read small portionsMonitor loop (prefer session files over task output):
5.1. Start background check (sleep duration by phase: investigation/planning 60s, implementation 120-180s, quality 120s, testing 60s):
Bash(command="sleep 60 && cat [SESSION]/_overview.md", run_in_background=true)
Returns task_id (e.g., "b155903")
5.2. Wait for result - DO NOT SKIP, do immediately after 5.1:
TaskOutput(task_id="b155903", block=true, timeout=600000)
Note: 600000ms (10 min) is the max allowed timeout.
5.3. Extract from result: Phase, Iteration, Total Iterations, Blocked, Last Action, Next, last 3 Flow Log entries
5.4. Get recent commits:
git -C [WORKING_DIR] log --oneline -3
5.5. Report to user:
Samocode Progress [HH:MM elapsed]
--------------------------------
Phase: [phase] (Iteration N/Total)
Last: [Last Action]
Next: [Next]
Recent commits:
- [hash] [message]
Flow:
- [last 2-3 Flow Log entries]
5.6. Check stop condition:
Phase: done → report final summary, STOPBlocked: contains yes or waiting → handle accordingly (see Handling Waiting States), STOPIMPORTANT: On STOP, clean up monitoring. When samocode finishes (done/blocked/waiting), do NOT leave pending background sleep tasks running. Stop any active monitoring task via TaskStop before reporting the final status. This prevents stale notification floods.