Portfolio

Maintain the portfolio using the data model, workflow and Beads conventions. The schema lives in the data-model document; do not duplicate it here.

Start from AGENTS.md and the current roadmap, then read only the relevant records and sources. Accept the user's outflow, infer a useful proposal from evidence, and ask only for consequential missing facts. Existing authorisation to update records is sufficient; do not introduce a repeated approval loop.

Find the record

Search current initiative/project Markdown by title, slug, aliases and purpose, then inspect linked Beads. Use the generated portfolio index when fresh, and follow its regeneration instructions after metadata changes. If it is missing or stale, use rg --files initiatives projects for directories that exist and search the records directly. Include legacy prose-only project files in duplicate checks. Supporting workstream notes are context, not automatically separate projects.

If the request clearly updates existing work, update its record. If two plausible records overlap and the intended boundary is uncertain, explain the match and ask whether to update or create separately. Do not create a near-duplicate to avoid resolving the match.

Add

Distinguish an enduring initiative, a bounded project and a small task needing no portfolio record. Prepare the minimum metadata from the user's facts and existing context. Use explicit unknowns for unconfirmed current ownership, status and relationships; preserve historical claims and source references separately. Do not infer present activity from an old Active cell, a recent file edit or a prose planning phase.

For a record, use the model's filename and body conventions. Write purpose/outcome, source links, and only the additional framing needed. Link existing relevant tasks/epics. For genuinely new actionable work, check for duplicates and create it in the canonical tracker within the user's authorised scope. An initiative does not need a standing Bead, and a record does not need a Markdown task checklist.

When creating or updating a project with a corresponding Beads epic, include that epic's verified ID in the existing beads: frontmatter list. Reuse the epic already associated with the project; do not create a duplicate or mirror its child-task queue. For example, projects/2605-project-management-infrastructure.md lists lip-tqk in beads:.

For a new project, allocate its filename as projects/YYDD-<slug>.md: inspect projects/, numerically sort existing project prefixes for the current year, and increment the highest sequence (start at 01 if none exist). The filename prefix is the ID; no duplicate frontmatter ID or allocator is needed. Follow the data model's stability, non-reuse and collision rules, rechecking before committing. Use the full filename stem in Beads project: labels and links. Do not number initiatives, roadmap documents or supporting notes as projects.

Update, pause or close

Read the existing record and actual relevant tracker entries before changing either. Preserve source links, decisions, ownership, unrelated work and existing task relationships. Update only supported portfolio facts and append a dated status note. Put progress evidence or decisions in context; put assignments, blocking and task completion in the tracker. If a task already exists, update or link it rather than creating another.

Pause or close according to the data model and actual evidence. Preserve history. Finishing one child task does not complete a project, and finishing one project does not finish its initiative. If next actions are requested, inspect the actual task queue and dependencies; report/update that queue rather than copying it into Markdown.

Associate initiative work through labelled roots and standalone tasks, with descendants found through the tree. Do not require labels on every child or claim a basic label filter includes them. Use verified query tooling when available; otherwise inspect the relationships and state coverage limitations.

Review and reconcile

Report duplicate candidates, missing/uncertain metadata, invalid parent references, stale evidence, unresolved source conflicts and legacy files still outside the typed inventory. A lifecycle status and a planning phase are different: Status: shaping alone does not prove current activity. Keep unverified records separate from confirmed active work.

Apply supported corrections within the requested review/migration scope. Ask for consequential decisions that evidence cannot resolve, such as conflicting ownership or whether two efforts are the same. Do not silently promote historical source facts into current metadata or delete old records because a newer view exists. Capture remaining actionable follow-up in Beads.

For migration, preserve an auditable source-to-record mapping, including aliases, original claims and exclusions. Follow the agreed pilot-before-bulk-import gate. Do not modify source spreadsheets or publish private material merely because they were inputs to a migration.

Verify and hand off

Parse changed frontmatter; check schema, lifecycle/phase, unique identifiers, parent references and links. Read back changed Beads and confirm no duplicate task queue was introduced. Commit substantive changes, excluding unrelated edits. Report what changed, what was verified and what remains uncertain; update the execution Bead with actual evidence.