Index of every page on this site: llms.txt
All skills
kunchenguid avatar

/project-management

@427056c
by Kun Chenkunchenguid/firstmate9k stars
2,779
Run it yourself

Load before adding, creating, removing, or initializing a project. Cloning or registering a project is add intake and uses the same trigger.

Use this Skill: https://skilld.dev/gh/kunchenguid/firstmate/project-management

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈40 tokens for metadata: the name and description. ≈2.3k when used: this file.

Description uses 2.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈161 characters, or 2.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

project-management

Use this procedure before adding, creating, removing, or initializing a project. Cloning or registering a project is add intake and uses the same trigger. This skill is the single owner of Firstmate's project-management procedure. It does not replace secondmate-provisioning, which owns project clones inside persistent secondmate homes.

Preconditions and registry

Projects live flat under projects/, and data/projects.md is the private fleet registry. Use the registry format and parser contract owned by the header of bin/fm-project-mode.sh. Keep each registry description useful for identifying the project, but keep delivery posture, captain-private state, and detailed project knowledge in their existing designated homes. Do not turn the registry into project documentation.

Before adding, cloning, creating, or registering any project in the main home, inspect the authoritative data/secondmates.md routing table and judge every existing natural-language scope: against the proposed project or domain. Apply AGENTS.md section 7's authoritative secondmate routing rules; if an existing scope owns that domain, route the new-project operation or work there instead of creating or registering a duplicate main-home clone. Absence from the main data/projects.md registry is never evidence that no second mate owns the domain. If the owning second mate cannot accept the route, report that concrete blocker or obtain an explicit captain redirection rather than silently duplicating the project in the main home.

Resolve the project name, destination, delivery posture, and autonomy posture before changing local or remote state. Keep a newly added clone and its registry entry consistent, and roll back only artifacts created by the incomplete operation when a later initialization step fails and that rollback is safe. Do not overwrite or repurpose an existing path.

Delivery posture

The registry records the project's standing delivery posture and optional ship-branch prefix, which are the captain's defaults rather than any task's answer. AGENTS.md section 7 owns how each task's concrete mode, yolo, and branch prefix are resolved at intake and passed explicitly to the brief, the spawn, and any promotion. Choose that posture when adding or creating the project:

  • no-mistakes runs the full validation pipeline before a PR.
  • direct-PR pushes and opens a PR without the no-mistakes pipeline.
  • local-only has no required remote or PR and lands only through the approved local fast-forward path.
  • no-mistakes-prod-only is a conditional policy rather than one flat mode: genuinely internal-only tooling, automation, contributor or operator process, and release or submission work ships direct-PR, while product-facing, mixed, and uncertain work ships no-mistakes.

no-mistakes-prod-only is the default for a newly added or created remote-backed project when the captain specifies nothing, and a project with no remote defaults to local-only. State that resolved default while confirming the source, local name, and posture instead of asking the captain to choose from scratch, and record a flat mode instead whenever they ask for one. Existing registry entries keep the meaning they already have and are never migrated or reinterpreted, so a legacy entry with no bracket stays no-mistakes. Registering a conditional policy is a one-time choice and never requires classifying any change; the per-task surface classification happens at each task's intake, and internal-only is never inferred from file location or project name.

The optional +yolo posture changes merge authority only and does not change the delivery mode. Default it off for every project and every posture, and enable it only on the captain's explicit instruction. AGENTS.md section 7 owns the merge-authority contract.

The optional forge= token records which forge the project's remote actually is; its values are forge=gerrit, forge=forgejo, and forge=external. It is orthogonal to the mode and to +yolo, so it is never derived from either, and it is never inferred at use time from a remote name, host, port, or push target. At add or create intake, run bin/fm-forge-detect.sh projects/<name> once the clone exists and propose its answer alongside the posture; the captain's confirmation is what binds it, and the registry token is the durable record of that confirmation. Never register the binding from detection alone, and never re-derive it later from the clone. bin/fm-forge-detect.sh never proposes forge=forgejo, so for a remote that may be Forgejo or Gitea ask the captain and register forge=forgejo only on that confirmation. A forge composes with no-mistakes, direct-PR, and no-mistakes-prod-only (forge=external with direct-PR only), and the registry refuses it on local-only, which publishes nothing; a Gerrit-hosted project kept local registers local-only with no forge token. yolo is inactive on a forge=gerrit project, so never propose +yolo alongside it. forge=external marks a project whose review tool uploads its own snapshot, so workers never push a task branch to its shared origin: it is never detected, so register it only on the captain's confirmation, as [direct-PR forge=external] with no +yolo, and only once the home has config/external-review.md (docs/configuration.md "External review tool"). bin/fm-project-mode.sh's header owns the binding and bin/fm-dod-lib.sh owns what it changes for a worker. The optional pr=manual token marks a no-mistakes project whose PR title and body a person writes, so the pipeline's pr step must not rewrite them; register it only on the captain's confirmation, with no forge= token (docs/configuration.md "PR text selection").

Add or clone an existing project

Confirm the source URL, local project name, delivery posture, and autonomy posture, stating the resolved default for each rather than asking the captain to invent one. Clone into projects/<name> and add the registry entry only after the destination is known to be unused. A no-mistakes or no-mistakes-prod-only project must have an origin remote and must complete the initialization procedure below, because a conditional policy's product-facing work runs the pipeline while its internal-only work still takes the direct PR. A direct-PR project needs an origin remote but skips no-mistakes initialization. A local-only project may have no remote and skips no-mistakes initialization. Confirm the matching CLI is authenticated for a non-GitHub host: glab auth login for a GitLab project, whose merge watch and merge use glab, or a tea login add for a forge=forgejo project, whose merge watch, merge, and generated ship brief use tea.

Create a project

Creating a GitHub repository is outward-facing. Before making that remote change, propose the repository name, owner or organization, visibility, and delivery posture, defaulting visibility to private and the posture to no-mistakes-prod-only, then obtain the captain's explicit consent for those exact values; a stated default never replaces that consent. Use gh-axi for the approved GitHub operation and consult its current help rather than relying on remembered flags. After remote creation succeeds, clone it locally, add the registry entry, and initialize it according to its delivery posture.

For a purely local-only project, create a local Git repository under its unused projects/<name> path, add the registry entry, and make no GitHub call. A new repository has no commit, and spawn refuses to dispatch work into a project with an unborn HEAD. Tell the captain that the project needs a first commit. The captain's request to create that local project authorizes this local initialization, but it does not authorize an unmentioned remote repository.

Initialize

Run no-mistakes initialization only for no-mistakes and no-mistakes-prod-only projects:

(cd projects/<name> && no-mistakes init && no-mistakes doctor)

Initialization configures the local gate and does not vendor a no-mistakes skill into the project. Do not create a commit merely because initialization ran. If doctor reports an environment, authentication, or daemon problem, resolve that blocker before dispatching work and never restart the shared daemon from a project operation.

Remove

Project removal is destructive. First obtain the captain's explicit removal decision, then inspect the current digest and authoritative repositories for in-flight or queued work, registered secondmate clones, linked worktrees, dirty files, unpushed commits, and any other unlanded work. If any dependency or unlanded work exists, stop and report it before changing anything. Never issue a raw removal command from Firstmate. Once that preflight confirms none of the above and the captain's approval is concrete, AGENTS.md hard rule 1's captain-approved project operation exception authorizes firstmate to remove the clone directly and update its registry entry to match. When a clone has already been removed through an approved removal, or the registry is provably stale because no clone exists, remove its registry line so navigation matches reality.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning4mo3 checks · Risk SAFE
  • Gen Agent Trust Hub4mo

    This skill provides a standard procedural framework for managing software projects, including cloning, creation, and initialization. It incorporates best practices by requiring explicit user consent for destructive actions and outward-facing operations.

  • Socket4mo

    1 alert: gptSecurity

  • Snyk4mo

    Risk: LOW · No issues

Signed by skilld at 427056c. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated 3 weeks ago
user-invocable
false
metadata
{
  "internal": true
}

README badge

README badge for kunchenguid/firstmate/project-management