# Soho Project Start > Use as the Soho project-start/context-engineering skill when starting a new project, major spec, PRP, architecture brief, agent handoff, or workflow that must keep durable project markdown surfaces aligned, including AGENTS.md, CLAUDE.md, CODEX.md, README.md, ARCHITECTURE.md, PLANNING.md, TASK.md, lessons.md, docs/specs, docs/plans, docs/receipts, Linear, and issue-tracker or handoff notes. Use when this capability is needed. - Skill: `tomevault-io/soho-project-start` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/soho-project-start` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/soho-project-start/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/soho-project-start --- # Soho Project Start Use this with `using-soho` before substantial project/spec work. The goal is a context package that future agents can execute from, not a chat-only plan. ## Mode - Use `recommend` when the project direction or ownership is still undecided. - Use `solo` when one agent can inspect, write the context package, and verify it. - Use `swarm` only when independent architecture, product, security, design, or implementation tracks genuinely need separate passes. Record the mode and runtime in the receipt. ## 1. Orient Before writing, inspect the existing project truth: ```bash pwd git status --short --branch find . -maxdepth 3 -type f \( -name 'AGENTS.md' -o -name 'CLAUDE.md' -o -name 'CODEX.md' -o -name 'README.md' -o -name 'ARCHITECTURE.md' -o -name 'PLANNING.md' -o -name 'TASK.md' -o -name 'lessons.md' -o -path './docs/*' \) | sort ``` Also inspect local equivalents when present: - `BUILDERBOT.md`, `GEMINI.md`, `GOOSE.md`, `.cursor/commands/` - `.agentops/context/`, `.agentops/tasks/`, `.agentops/receipts/` - `docs/specs/`, `docs/plans/`, `docs/receipts/` - open PR, Linear, Slack, or handoff notes referenced by the user or repo Do not create every possible file. Use existing conventions first. For a new empty project, the safe default is `README.md`, `AGENTS.md`, `docs/specs/`, `docs/plans/`, and `docs/receipts/`. ## 2. Build The Context Package Borrow the useful Context Engineering pattern: 1. Initial request: what is being built and why. 2. Project rules: durable agent instructions and constraints. 3. Examples and patterns: files or prior artifacts to mirror. 4. PRP/spec: implementation blueprint with enough context for one-pass execution. 5. Validation gates: commands the agent can run and iterate on. 6. Receipt: what changed, what is proven, and what is not claimed. The package must answer: - Problem statement and user-visible outcome. - Current truth layer: working tree, `HEAD`, generated artifacts, external systems. - Non-goals and privacy/safety constraints. - Source inventory and ownership. - Existing patterns/examples to follow. - Architecture decision and tradeoffs. - Interfaces or artifact contracts. - Manual curation or override path when generated output is involved. - Tests, validation commands, and success criteria. - Open questions with owner or next action. ## 3. Update Markdown Surfaces In Lockstep Update only the files that are present, expected by the repo, or necessary for the new project. - `AGENTS.md`: repo-specific agent rules and required read order. Preserve managed blocks exactly. - `CLAUDE.md` / `CODEX.md`: runtime-specific guidance only when the repo uses those files. Keep them aligned with `AGENTS.md` instead of creating conflicting rules. - `README.md`: human entrypoint, run commands, and current status. - `ARCHITECTURE.md` / `PLANNING.md`: system design, boundaries, source-of-truth decisions, and sequencing. - `TASK.md`: active tasks, discovered work, and dated next actions. - `lessons.md`: durable lessons and repeated failure modes only. Do not use it as a scratchpad. - `docs/specs/`: product and technical spec. - `docs/plans/`: executable implementation plan with exact paths and validation. - `docs/receipts/`: proof, commands run, outputs, blockers, non-claims, and external update state. - Issue tracker / Linear / PR notes: post only when explicitly authorized; otherwise draft exact text and label it not posted. If two files would say the same thing, prefer one canonical file and add a pointer from the other. Avoid duplicate narratives that can drift. ## 4. PRP / Spec Minimum A build-ready PRP or spec needs: - Goal, why, and user-visible behavior. - Current codebase/project tree and desired tree. - Files to create or modify. - Data models, interfaces, or artifact schemas. - Implementation steps in execution order. - Validation gates that are actually runnable. - Risks, failure modes, and mitigations. - Success metrics or acceptance criteria. - Explicit fixture/local proof versus live integration proof. For agent-facing PRPs, include exact files and examples to read. Do not rely on a model guessing the project conventions. ## 5. Validation Before claiming the context package is ready: - Re-read the changed markdown files for contradictions. - Verify JSON/YAML receipts or schemas parse when applicable. - Verify referenced files exist or are explicitly marked future/nonexistent. - Verify validation commands are concrete, not placeholders. - Re-run `git status --short --branch` and classify unrelated dirty work. - Record any live-system action as `posted`, `drafted`, `blocked`, or `not attempted`. ## 6. Receipt End with a receipt containing: - mode and runtime - files created or updated - commands run and results - context-engineering inputs used - live systems contacted or explicitly not contacted - what is proven now - what is not claimed - next recommended action ## Guardrails - Preserve managed blocks and user-owned edits. - Do not overwrite existing project doctrine with generic templates. - Do not claim fixture proof as live integration proof. - Do not create `CLAUDE.md`, `CODEX.md`, or `lessons.md` just to satisfy a checklist if the repo has another canonical context surface. - Do not post Slack, Linear, email, or PR comments without explicit authorization. - If sending on the user's behalf after authorization, prefix the message with `🤖`. --- > Source: [SoheilOlia/Soho](https://github.com/SoheilOlia/Soho) — distributed by [TomeVault](https://tomevault.io).