project

SKILL.md

---
name: project
description: Create and manage Polly Projects — named, persistent knowledge bases maintained by Polly as a directory of structured markdown files. Use when the user asks to create a project, start tracking a topic or work stream, add a source to a project, query a project, run a health check (lint) on a project, or asks about any existing project. Triggers include phrases like "start a project for", "create a project", "add this to my project", "what does my project say about", "health check my project", "update my project", or any request to maintain a persistent knowledge base around a specific topic or work stream.
---

# Project Skill

Polly Projects are named, persistent knowledge bases — owned and maintained by Polly as a directory of structured markdown files in `~/data/projects/<project-slug>/`. The canonical entry point is `README.md`, which serves as both the schema (how the project is organized and maintained) and the index (a catalog of every file).

Read `references/project-spec.md` for the full concept and design rationale. Read `references/readme-template.md` for the starter README template.

---

## Project Registry

Until a platform-level project registry exists, track active projects in memory under the key `polly_projects_registry` as a JSON object:

```json
{
  "project-slug": {
    "name": "Human-readable name",
    "path": "~/data/projects/project-slug",
    "created": "YYYY-MM-DD",
    "description": "One-line description"
  }
}
```

Always check memory for `polly_projects_registry` before any project operation. If a user references a project by name, match it against the registry.

---

## Mode 1 — Create a Project

### Conversational path
User says: "Start a project for X" or "I want to track everything on Y"

1. Ask (one message, not a list of separate questions): what's the scope, what kinds of sources will come in, and what outputs matter most
2. Propose a directory structure and a short README schema draft — ask for confirmation or adjustments
3. Create the directory: `mkdir -p ~/data/projects/<slug>/`
4. Write `README.md` using `references/readme-template.md` as the base, customized for this project
5. Register in memory under `polly_projects_registry`
6. Close the loop: confirm what was created and offer to set up a weekly lint task

### Idea file path
User pastes a brief, goal statement, or source document.

1. Read it and infer: project name, scope, likely directory structure, initial conventions
2. Propose the structure — confirm before creating
3. Create directory + README.md as above, then optionally ingest the pasted content as the first source (Mode 3)

---

## Mode 2 — Navigate a Project

Before touching any project files, always read `README.md` first:
- **Schema section**: understand the conventions and ingest workflow for this project
- **Index section**: find which files are relevant to the current request

Never guess at file locations — always derive from the index.

---

## Mode 3 — Ingest a Source

A source can be a URL, a pasted document, a file, or a conversation summary.

**Default workflow** (used when the project's README schema doesn't specify a different one):

1. Read/fetch the source
2. Write a source summary to `/sources/<domain-or-title>-<YYYY-MM-DD>.md`
3. Update relevant content pages (entity pages, topic pages, etc.)
4. Update the `## Index` in README.md if new files were created
5. Append to `log.md`: `## [YYYY-MM-DD] ingest | <source title>`
6. Close the loop in chat: "I've updated X pages in your [project name] project."

Always follow the project's own schema ingest workflow if one is defined — it takes precedence over the default.

---

## Mode 4 — Query a Project

1. Read `README.md` → identify relevant files from the index
2. Read those files → synthesize an answer with inline citations
3. If the answer is reusable (a comparison, analysis, or synthesis), offer to file it as a new page
4. If filed: add to index, append to log as `## [YYYY-MM-DD] query | <brief description>`

---

## Mode 5 — Lint a Project

Run the lint checklist defined in the project's README schema. If no checklist is defined, use the default:

- Pages not updated in 60+ days → flag as potentially stale
- Files in the project not listed in the index → add them
- Concepts mentioned across pages but lacking their own page → create stubs
- Orphan pages (no inbound links from other pages) → flag
- Contradictions between pages → flag inline with `> ⚠️ Contradicts [file] — [note]`
- Gaps that could be filled with a web search → suggest 2–3

Deliver results as a brief summary in chat. File a lint entry in `log.md`: `## [YYYY-MM-DD] lint | <N issues found, N resolved>`

Remind the user that lint can run automatically as a weekly scheduled task if they'd like to set one up.

---

## Current Limitations

Be transparent about these when relevant:

- **No platform registry**: projects are tracked in memory — this is fragile across sessions. The full platform feature (TODO-411) will add a proper registry.
- **No filing hooks**: Polly won't proactively file project-relevant content from conversations unless asked. For now, the user triggers filing explicitly.
- **No automated lint scheduling**: Polly can help set up a manual scheduled task, but it's not seamlessly integrated yet.