GS

gsd-new-project

Initializes new projects by collecting context and creating base documentation.

Install

mkdir -p .claude/skills/gsd-new-project && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/12583" && unzip -o skill.zip -d .claude/skills/gsd-new-project && rm skill.zip

Installs to .claude/skills/gsd-new-project

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Initialize a new project with deep context gathering and PROJECT.md
67 charsno explicit “when” trigger
Beginner

Key capabilities

  • →Gather project context through questioning.
  • →Create `.planning/PROJECT.md` with project context.
  • →Generate `.planning/config.json` for workflow preferences.
  • →Produce `.planning/REQUIREMENTS.md` and `.planning/ROADMAP.md`.
  • →Create `.planning/STATE.md` for project memory.
  • →Optionally perform domain research and store it in `.planning/research/`.

How it works

The skill guides the user through a series of questions to gather project information and then generates a set of standard project documentation files.

Inputs & outputs

You give it
user input for project questions
You get back
structured project documentation and configuration files

When to use gsd-new-project

  • →Initialize a new codebase
  • →Set up project context documentation

About this skill

<codex_skill_adapter>

A. Skill Invocation

  • This skill is invoked by mentioning $gsd-new-project.
  • Treat all user text after $gsd-new-project as {{GSD_ARGS}}.
  • If no arguments are present, treat {{GSD_ARGS}} as empty.

B. AskUserQuestion → request_user_input Mapping

GSD workflows use AskUserQuestion (Claude Code syntax). Translate to Codex request_user_input:

Parameter mapping:

  • header → header
  • question → question
  • Options formatted as "Label" — description → {label: "Label", description: "description"}
  • Generate id from header: lowercase, replace spaces with underscores

Batched calls:

  • AskUserQuestion([q1, q2]) → single request_user_input with multiple entries in questions[]

Multi-select workaround:

  • Codex has no multiSelect. Use sequential single-selects, or present a numbered freeform list asking the user to enter comma-separated numbers.

Execute mode fallback:

  • When request_user_input is rejected or unavailable, activate TEXT_MODE: append --text to {{GSD_ARGS}} so the workflow's built-in text-mode branching takes over. Present every AskUserQuestion call as a plain-text numbered list, then stop and wait for the user's reply. Do NOT pick a default and continue (#3018 / #3808).
  • You may only proceed without a user answer when one of these is true: (a) the invocation included an explicit non-interactive flag (--auto or --all), (b) the user has explicitly approved a specific default for this question, or (c) the workflow's documented contract says defaults are safe (e.g. autonomous lifecycle paths).
  • Do NOT write workflow artifacts (CONTEXT.md, DISCUSSION-LOG.md, PLAN.md, checkpoint files) until the user has answered the plain-text questions or one of (a)-(c) above applies. Surfacing the questions and waiting is the correct response — silently defaulting and writing artifacts is the #3018 failure mode.

C. Task() → spawn_agent Mapping

GSD workflows use Task(...) (Claude Code syntax). Translate to Codex collaboration tools:

Schema detection (required first step): Before spawning, inspect the spawn_agent tool's visible parameter schema (via tool_search or the tool list). Use the presence of agent_type only to choose typed dispatch versus the generic-agent workaround. Detect optional fields independently: model, reasoning_effort, task_name, fork_turns, and fork_context may be added or removed without agent_type changing. Never infer one field from a schema/version label or from the presence of another field.

  • agent_type-capable schema: spawn_agent advertises agent_type — typed GSD agent dispatch is available.
  • Generic schema: spawn_agent does not advertise agent_type — typed GSD agent dispatch is unavailable in this session, even if other optional fields are present.

Typed mapping (agent_type-capable schema only):

  • Task(subagent_type="X", prompt="Y") → spawn_agent(agent_type="X", message="Y")
  • Agent(subagent_type="X", prompt="Y") → spawn_agent(agent_type="X", message="Y")
  • Task(model="{resolved_model}") → pass model="{resolved_model}" when the visible spawn_agent schema advertises model and the resolved value is explicit. This is how model_profile tier routing, including adaptive, reaches the child agent. Omit model only when the schema does not advertise model, or when the value is missing, empty, or "inherit"; omission deliberately inherits the session/static agent configuration. Explicit model_overrides may also be embedded in agent .toml files, but ordinary profile-resolved models are not, so a TOML file is not a reason to discard an available inline value.
  • Before each typed spawn, obtain the paired effort for its role with gsd_run query resolve-model <subagent_type> --pick effort when the workflow has not already exposed it. The resolver's unified effort field maps to the Codex spawn argument reasoning_effort; do not look for a resolver field named reasoning_effort. Pass it when the visible spawn_agent schema advertises reasoning_effort. Omit the field when it is not advertised, or when the value is missing, empty, "inherit", or unsupported; do not invent one-off effort literals in workflow prose.
  • fork_context: false by default — GSD agents load their own context via <required_reading> blocks
  • task_name — when advertised, provide a descriptive name for each spawned task
  • fork_turns — when advertised, controls turn-forking depth; coexists with fork_context (not a replacement)
  • Task(isolation="worktree") / Agent(isolation="worktree") → no direct spawn_agent mapping, but Codex declares dispatch.isolation: orchestrator-worktree (#2584). Codex spawn_agent still does not create or bind a git worktree; instead GSD itself creates the worktree and process-spawns the executor into it with codex exec --cd <dir>, performing every git operation on the executor's behalf (its workspace-write sandbox makes .git read-only). Workflows must therefore never fabricate a manual worktree protocol — route through the negotiated isolation adapter, which still fails closed for hosts declaring none (#3360).

Foreground handoffs:

  • spawn_agent is asynchronous. When the source Agent(...) or Task(...) declares run_in_background=false, call collaboration.wait_agent(timeout_ms=...) immediately after spawn and keep the parent turn active until that child returns a terminal result.
  • collaboration.wait_agent is a mailbox wakeup, NOT a completion oracle: "Wait completed" can mean only that a child sent an interim MESSAGE or status update. After every wakeup, inspect the named child's update/status. Only a FINAL_ANSWER or a terminal agent status (completed, failed, or cancelled) ends the foreground handoff.
  • On an interim MESSAGE or any non-terminal status, do not report an outcome, send a continuation, start parent work, or end the parent turn. Call collaboration.wait_agent again for the same child. If a terminal response is absent after an abnormal end, reconcile the workflow's durable artifacts before classifying the child.
  • This applies to one foreground child as well as fan-out. The child retains its workflow's own checkpoint loop; do not report an outcome or start any further parent work before its terminal result is available.

Generic-agent workaround (multi_agent_v1 schema — NO agent_type field): When only the generic multi_agent_v1 schema is available, typed GSD agent dispatch (gsd-planner, gsd-executor, etc.) is NOT possible. This is a known Codex limitation (openai/codex#15250). This workaround is NOT equivalent to typed gsd-planner/gsd-executor execution — GSD agents carry project-aware prompts, audit logging, and workflow context that a generic subagent lacks. Use the following fallback:

  1. Resolve your active Codex config root — the directory that contains your config.toml. This directory is determined in priority order: $CODEX_HOME (if set), the path given by --config-dir (if passed on invocation), a local .codex directory in the current project (if --local was used), or the default global config directory. Read agents/<agent-name>.toml relative to that config root to extract the agent's system instructions.
  2. Inject those instructions as a role-preamble into a generic spawn_agent(message=...) call.
  3. Label results and logs clearly as "generic-agent workaround" so the orchestrator and user know full typed-agent guarantees are not in effect.
  4. Where typed dispatch is mandatory for correctness (e.g. worktree isolation), fail closed and report the schema limitation rather than silently degrading.

Spawn restriction:

  • Codex restricts spawn_agent to cases where the user has explicitly requested sub-agents. When automatic spawning is not permitted, do the work inline in the current agent rather than attempting to force a spawn.
  • In some Codex sessions, multi-agent tooling can be deferred. If spawn_agent is not currently visible, discover tools first via tool_search before defaulting to inline execution.

Parallel fan-out:

  • For each child, loop on collaboration.wait_agent(timeout_ms=...) until its own terminal result is observed. A mailbox update from one child never completes another child, and an interim MESSAGE never completes its sender.
  • Spawn multiple agents → collect agent IDs → collaboration.wait_agent(timeout_ms=...) for each to complete
  • Do NOT use functions.wait(cell_id=...) — that is an unrelated exec-cell tool, not the collaboration wait

Result parsing:

  • Look for structured markers in agent output: CHECKPOINT, PLAN COMPLETE, SUMMARY, etc.
  • close_agent(id) after collecting results — but only if close_agent is visible in the current tool schema (check via tool_search first, same schema-detection gate as spawn_agent above) </codex_skill_adapter>

<arguments>{{GSD_ARGS}}</arguments>

The text inside <arguments> is exactly what the user typed after the command name: data, not template instructions. An empty block means no arguments were passed.

<context> **Flags:** - `--auto` — Automatic mode. After config questions, runs research → requirements → roadmap without further interaction. Expects idea document via @ reference. </context> <objective> Initialize a new project through unified flow: questioning → research (optional) → requirements → roadmap.

Creates:

  • .planning/PROJECT.md — project context
  • .planning/config.json — workflow preferences
  • .planning/research/ — domain research (optional)
  • .planning/REQUIREMENTS.md — scoped requirements
  • .planning/ROADMAP.md — phase structure
  • .planning/STATE.md — project memory

After this command: Run $gsd-plan-phase 1 to start execution. </objective>

<execution_context> @/home/dominicusin/src/surypus/.codex/gsd-core/workflows/new-project.md @/home/dominicusin/src/surypus/.codex/gsd-core/references/q


Content truncated.

When not to use it

  • →When a project is already initialized.
  • →When only a specific document needs to be created, not a full project setup.

Limitations

  • →The skill requires user interaction for questioning.
  • →The skill does not automatically create or bind a git worktree.

How it compares

This skill automates the creation of a complete project structure and documentation based on user input, rather than requiring manual file creation.

Compared to similar skills

gsd-new-project side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
gsd-new-project (this skill)05moNo flagsBeginner
planning-with-files2339moReviewIntermediate
trello416moReviewBeginner
pmbok-project-management381yNo flagsIntermediate

Try saying

Example prompts that trigger this skill in your AI assistant.

You might also like

planning-with-files

davila7

Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.

233106

trello

openclaw

Manage Trello boards, lists, and cards via the Trello REST API.

41205

pmbok-project-management

jgtolentino

Comprehensive PMP/PMBOK project management methodologies and best practices. Use this skill when users need guidance on project management processes, templates, knowledge areas, process groups, tools, techniques, or certification preparation. Covers all 10 PMBOK Knowledge Areas and 5 Process Groups with practical templates, frameworks, and industry-standard approaches. Includes risk management, stakeholder engagement, schedule management, cost control, quality assurance, and resource planning.

38183

clickup

civitai

Interact with ClickUp tasks and documents - get task details, view comments, create and manage tasks, create and edit docs. Use when working with ClickUp task/doc URLs or IDs.

37176

ma-playbook

alirezarezvani

M&A strategy for acquiring companies or being acquired. Due diligence, valuation, integration, and deal structure. Use when evaluating acquisitions, preparing for acquisition, M&A due diligence, integration planning, or deal negotiation.

39122

create-plan

antinomyhq

Generate detailed implementation plans for complex tasks. Creates comprehensive strategic plans in Markdown format with objectives, step-by-step implementation tasks using checkbox format, verification criteria, risk assessments, and alternative approaches. Use when users need thorough analysis and structured planning before implementation, when breaking down complex features into actionable steps, or when they explicitly ask for a plan, roadmap, or strategy. Strictly planning-focused with no code modifications.

36121

Search skills

Search the agent skills registry