projects-entities

Projects Entities

Author one consultant, project, or assignment record into a cogni-projects portfolio and register it in the portfolio manifest. This is the data-entry foundation the staffing-match engine, backfilling recommender, and partner-meeting dashboard all read from — every entity authored here is a row those later skills reason over.

Entities are Obsidian-browsable markdown files with YAML frontmatter. The full field contract lives in ../../references/data-model.md; read it before authoring so the frontmatter matches what validate-entities.py enforces.

Core concept

Each entity is one markdown file under its type's subdirectory of a portfolio:

• consultant → consultants/<slug>.md
• project → projects/<slug>.md
• assignment → assignments/<consultant>--<project>.md

Authoring an entity covers three effects: write the file, register a compact summary ref into the matching projects-portfolio.json array, and append a transition to .metadata/execution-log.json. Writing the file and registering it are separate tool calls, not a transaction — an interrupted run can leave an entity file on disk that the manifest does not yet reference. That state is repaired by re-running the skill for the same slug: registration is idempotent (register-entity.py upserts keyed on slug), so a repeated run never double-registers.

Workflow

Step 1: Locate the target portfolio

Find the portfolio directory the user means. If they name a slug, use cogni-projects/<portfolio-slug>/. Otherwise glob cogni-projects/*/projects-portfolio.json and, when more than one portfolio exists, ask which one. If none exists, tell the user to run /cogni-projects:projects-setup first — this skill authors into an initialized portfolio, it does not scaffold one.

Step 2: Determine the entity type and gather fields

Decide whether the user is authoring a consultant, project, or assignment, then gather the required fields for that type (ask only for what is missing):

Every entity, whatever its type, additionally requires type — which must match its containing subdirectory, or the validator errors — and slug. The per-type lists below are a quick reference — ../../references/data-model.md is canonical; if this list and the data model ever disagree, the data model wins:

• consultant — name, seniority, skills; optionally grade, location, available_from / available_until, allocation_pct, updated.
• project — name, client, strategic_impact (1–5); optionally open_roles, start_date / end_date, status, updated.
• assignment — the consultant and project slugs, role, start_date, end_date; optionally allocation_pct, status, updated. The slug is composite: <consultant-slug>--<project-slug>.

Derive the slug from the name (kebab-case) unless the user supplies one. For an assignment, confirm both referenced entities already exist under consultants/ and projects/ — read them first, which is also the guard against a dangling reference.

Step 3: Read siblings, then write the entity file

Read the existing entities in the target subdirectory so the new record is consistent with them (naming, skill vocabulary, role labels). If a file already exists at the target slug and it is not the same entity being re-authored, stop and ask the user to disambiguate the slug — writing would replace that record, and Step 5's upsert would report an ordinary updated, leaving the collision indistinguishable from an intentional re-run. Then write the single entity file with its YAML frontmatter per the data model. Write only the one entity file — never a summary, index, or batch file.

Step 4: Validate before registering

Run the validator against the new file and gate registration on its success:

python3 "${CLAUDE_PLUGIN_ROOT:-$(ls -td "$HOME"/.claude/plugins/cache/*/cogni-projects/*/ 2>/dev/null | head -1)}/scripts/validate-entities.py" "cogni-projects/<portfolio-slug>/<subdir>/<entity>.md"

The validator returns {"success": bool, "data": {"errors": [...], "warnings": [...]}, "error": str}. If success is false, fix each data.errors[] entry (they name the offending field and message) and re-run — do not register a malformed entity into the manifest. Run this step even though Step 5's script validates again: that script reports only an error count and points back here, so this is the run that surfaces the per-field errors needed to fix the file.

Read data.warnings[] too. An unknown field (ignored) warning is usually a misspelled key — the value is being dropped, not stored — so correct it against the data model before registering.

The validator checks frontmatter shape only: required keys, enums, slug casing, ISO dates and their ordering, numeric ranges. It does not resolve an assignment's consultant / project slugs to real entity files, so a passing run is not evidence the refs exist — reading both referenced entities in Step 2 remains the guard against a dangling reference.

Step 5: Register in the manifest and log the transition

Once validation passes, register the entity. Do not hand-edit projects-portfolio.json — run the script, which upserts the summary ref keyed on slug, bumps the manifest updated date, and appends the .metadata/execution-log.json transition in a single invocation (it re-runs the validator itself, so it refuses an entity the Step 4 gate would have caught):

python3 "${CLAUDE_PLUGIN_ROOT:-$(ls -td "$HOME"/.claude/plugins/cache/*/cogni-projects/*/ 2>/dev/null | head -1)}/scripts/register-entity.py" "cogni-projects/<portfolio-slug>" "cogni-projects/<portfolio-slug>/<subdir>/<entity>.md"

It returns the same {"success", "data", "error"} envelope; data.action is created or updated, which is how a re-run reports that it replaced an existing ref rather than adding a second one.

Step 6: Summarize

Report the file written, the manifest array it was registered in, and the validation result. Keep it short. Point to the next entity to author — for example, once a consultant and a project both exist, authoring the assignment that joins them.

Notes

• Scripts return {success, data, error} JSON, stdlib-only — both validate-entities.py and register-entity.py follow the plugin convention; do not add pip dependencies.
• The manifest is the source of truth for what exists in the portfolio; entity files hold full field values. Keep them consistent — every authored file has exactly one manifest ref.
• One entity per invocation keeps each write reviewable and the execution log legible. To author several, run the skill once per entity.