How to track AI-assisted projects with PROJECT_STATUS.md

One local file, readable by people and tools

PROJECT_STATUS.md is a small Markdown file describing a project’s reported focus, progress, blockers and next actions. StateConsole reads it into your local portfolio instead of asking you to reconstruct context from old chats. You can read and edit it without StateConsole.

Put a regular file named exactly PROJECT_STATUS.md directly in the project’s root folder — the folder you register in StateConsole. A file in a nested folder is not read. Keep credentials, private details and absolute local paths out of it.

Connect your project

1. In the Windows desktop app, open Projects, choose Add local project and select the project folder.
2. Review the detected folder and markers, adjust the display name, registration status or color if needed, then choose Add project. Your repository stays in place.
3. Check Project status file in Project Details. Ready means the file parsed successfully, not that its reported work has been verified. If it is missing, choose Set up with AI agent for copyable guidance, or Create starter status file and confirm creation. StateConsole never overwrites an existing file. You can also skip setup and return later.
4. Save the file in your editor or coding agent. StateConsole watches the registered root file locally; use Refresh status file if you need to recheck it.

The supported format

Save as UTF-8, using LF or Windows CRLF line endings. Start with --- on the first line and close the frontmatter with another ---. These six fields are required, once each:

schema_version

Integer 1.

project

A non-empty name, up to 120 characters.

status

active, planning, on_hold, completed or archived.

phase

A non-empty current phase, up to 240 characters.

progress

An integer from 0 to 100, without a percent sign.

updated

A real calendar date in exact YYYY-MM-DD form.

Body sections are optional. The recommended starter includes all eight headings shown below; use their exact English names and a single #. Their order is not enforced. Body text may be in any language. Leave unknown or empty sections empty rather than inventing work.

Current focus takes plain paragraphs. Other sections take one-line - or * bullets; checkboxes use [ ], [x] or [X] followed by a space and text. Useful links takes one link per bullet, such as the project-relative Markdown link below or Label: https://stateconsole.com/. HTTP(S) links must have a host and no embedded credentials; relative links must not use absolute prefixes, parent-directory traversal, backslashes, colons, percent escapes or whitespace. Links are displayed as text, not fetched automatically.

A complete fictional example

Lantern Notes is fictional. This schema-version-1 example includes every canonical section. Adapt the facts and date to your own project; the relative checklist link is illustrative.

---
schema_version: 1
project: Lantern Notes
status: active
phase: Search and filtering
progress: 68
updated: 2026-10-07
---

# Current focus

Make saved notes easy to find by title and tag.

# Next actions

- [ ] Review search QA results
- [ ] Validate empty search results

# In progress

- [ ] Add tag filtering

# Blocked

- Waiting for a decision on case-sensitive tag names.

# Recently completed

- [x] Added title search and checked matching titles locally.

# Testing required

- [ ] Check combined title and tag filters
- [ ] Check keyboard navigation through search results

# Important decisions

- Keep notes and search indexes local.

# Useful links

- [Search checklist](docs/search-checklist.md)

Ask your coding agent to maintain it

Open Set up with AI agent, choose Codex, Claude Code or Generic AI coding agent, and copy the guidance into the agent working in that repository. Review its changes, then return to StateConsole. This is a prompt you choose to paste, not a direct integration.

Ask the agent to update the file after meaningful work, preserve the schema, and change updated only when the content materially changes. Record actual checks and uncertainties. Keep unverified work under Testing required. If you add a maintenance rule to existing agent instructions, merge it deliberately without replacing those instructions.

Agent-reported progress is not independent proof that work or testing has been completed. A value of 100 or a checked item is a report, not verification. Review the changes and test evidence yourself. StateConsole does not run the agent or those tests.

What refreshes automatically — and what does not

StateConsole reads the required fields and supported sections, watches for local file changes and refreshes the reported status. Valid next actions can appear as Dashboard suggestions, and open blockers can contribute to attention counts. Registration status and existing tasks also affect the Dashboard.

You or your agent still write the file. Reported name and status do not overwrite the app’s registration details; differences are flagged. Creating an app task from an eligible status item requires an explicit action in Project Details. It creates a one-way snapshot: later file edits do not update or complete that task, and task changes do not write back to the file. StateConsole does not scrape old AI chats.

Common mistakes and how to fix them

• Setup needed: check the exact filename and registered root folder. Create a file only if it is missing.
• Invalid frontmatter: include all six fields between the two delimiters. Use project, phase and updated, not the older project_name, current_phase or updated_date aliases. Use simple scalar values, not nested YAML, tags, aliases or multiline values.
• Invalid values: use schema 1, one of the five lowercase statuses, an integer progress value and a valid date.
• Missing or invalid section content: use exact level-one headings once each. Unknown headings and fields are ignored with warnings. Replace numbered or indented lists with one-line bullets; remove duplicate canonical headings.
• Invalid useful links: use HTTP(S) or safe project-relative links. Leave the section empty instead of adding a “No links” placeholder.
• Unreadable or oversized file: save as UTF-8 and keep the whole file at most 256 KiB, with frontmatter at most 8 KiB. Restore access to an unavailable folder; do not recreate an existing file to clear an error.

For Needs correction, read the diagnostic in Project Details. Use Open status file in default editor or Copy targeted repair prompt, make the smallest accurate correction, save and refresh. StateConsole does not silently repair existing files. For more help, visit Support.