Skip to content

project conf toml

Jump to bottom
Ian Smith edited this page Jun 3, 2026 · 3 revisions

.project-conf.toml — Design Document

Status: Draft, 2026-05-24.

Summary

The ticket-* skills currently identify their project via a single-word file .project-prefix at the working-directory root, containing MAZ, PLTF, etc. As multi-ticket, multi-backend (Linear / JIRA / GitHub Issues), and RAG-aware features land, that file needs to carry structured information. This document defines .project-conf.toml — a TOML file at the same path that replaces .project-prefix.

Goals

  • Plugin-wide single source of truth for project-level configuration.
  • TOML format for human readability and Python-native parsing (tomllib in 3.11+).
  • Namespaced sections so future features can land their config under a [<feature>] table without rev-ing the schema.
  • No auto-migration in skill code. The two existing legacy projects (mazzy/MAZ on Linear, lyos/PLTF on JIRA) are migrated by hand as one-off operations.

Non-goals

  • Per-user / per-machine config. .project-conf.toml is the project's config; user preferences live elsewhere if they exist.
  • Schema validation in the first cut. Skills tolerate unknown keys; missing required keys produce a clear error.
  • Hierarchical / inherited config (e.g. project-level + skill-level overlay). Single flat file.
  • Auto-walk up the directory tree. The file must be in the current working directory (same behavior as .project-prefix).

Format

Three flavors, one per backend.

Linear

system = "linear"
key    = "MAZ"

JIRA

system = "jira"
key    = "PLTF"

GitHub

system = "github"
key    = "iansmith/slopstop"
prefix = "BILL"                     # short identifier used in branch names + filesystem paths

[status_labels]
in_progress = "status:in-progress"
in_review   = "status:in-review"   # only present in the 4-state workflow; omit for 3-state

prefix is required for system = "github" because key (owner/repo) contains a slash and is too long for branch/path use. For Linear/JIRA, key already plays this role (MAZ, LOU, PLTF), so prefix is omitted.

[status_labels] is required for GitHub (no native state machine; states are encoded as labels). For Linear / JIRA, states are first-class and the section is omitted.

Reserved namespaces

Optional sections that consumers may use:

[rag]
endpoint     = "http://127.0.0.1:7777"    # default = 127.0.0.1:7777
corpus_scope = "linear"                   # default = same as top-level `system`

[exp]
label         = "experiment"              # applied to :exp-created tickets
branch_prefix = "exp"                     # default

[branch_prefixes]
feature = "feat"                          # default
fix     = "fix"                           # default
exp     = "exp"                           # default; mirrors [exp].branch_prefix

All optional. First-cut implementations may ignore [branch_prefixes] and hardcode defaults.

Required vs. optional keys

Key Required? Notes
system yes "linear" / "jira" / "github"
key yes system-specific identifier (Linear team key, JIRA project key, GH owner/repo)
prefix required for system = "github"; omitted for Linear/JIRA short token (3-6 chars), filesystem/branch-safe, used in $PREFIX-N ticket IDs (e.g. BILL-2). For Linear/JIRA, key already plays this role.
[status_labels].in_progress required for system = "github" else N/A
[status_labels].in_review required for system = "github" with 4-state workflow absent for 3-state
[rag].* no RAG behavior defaults if absent
[exp].* no :exp defaults if absent
[branch_prefixes].* no hardcoded defaults if absent

Lookup behavior

Skills read .project-conf.toml from the current working directory. If absent:

"No .project-conf.toml in cwd.
 Run /slopstop:gh-init (for GitHub) or create the file manually."

…and stop. Skills do not auto-walk up the directory tree.

Reading

import tomllib
with open(".project-conf.toml", "rb") as f:
    conf = tomllib.load(f)

system = conf["system"]                # required
key    = conf["key"]                   # required
labels = conf.get("status_labels", {})
rag    = conf.get("rag", {})
exp    = conf.get("exp", {})

Skills only consume the namespaces they need. Unknown keys are tolerated.

Companion file: state.toml

Per-ticket runtime state lives in a separate file inside each ticket directory:

~/.claude/ticket-active/$TICKET/state.toml

Its schema and write rules are fully defined in multi-ticket.md; this doc points at it only for cross-reference.

The two files are deliberately separate:

File Scope Lifetime Where
.project-conf.toml Project Long-lived, slow-changing Project cwd
state.toml Per ticket Runtime, transient ~/.claude/ticket-active/$TICKET/

Why no separate state.toml design doc

A standalone design doc for state.toml was considered and rejected for this slice:

  • The schema is small (≤6 fields: state, blocked_on, blocked_since, parent, plus reservations).
  • Its write rules are tightly coupled to the multi-ticket design — when state.toml is written or cleared is a per-skill decision in :start, :pause, :block, :archive, which are all defined in multi-ticket.md.
  • A separate doc would consist mostly of cross-references back to multi-ticket.md.

If state.toml grows non-trivial behavior independent of the skills that write it (e.g. an external watcher, schema versioning, migration tooling), a separate doc would become warranted. Until then, it lives inline.

Migration

No auto-migration code. For each existing legacy project, perform a one-off manual migration:

  1. Identify the correct system and key:
    • mazzy/MAZ → system = "linear", key = "MAZ".
    • lyos/PLTF → system = "jira", key = "PLTF".
  2. Write .project-conf.toml in the new format.
  3. Delete .project-prefix.

The skills' new code expects the new format only. No fallback to single-word reads — if a project hasn't been migrated, the skill prints the missing-file error and stops. This forces the migration to happen explicitly and prevents quiet drift.

Versioning

No explicit schema version field in the first cut. If the format ever needs incompatible evolution, add a schema_version = N key at the top and have skills branch on it. The TOML structure tolerates additions without breaking existing readers, so most evolution will be additive.

Prerequisites

None. This file's format is consumed by the new code in every other prerequisite (skill restructure, multi-ticket, RAG, ticket-gh-init). It's the lowest-level config primitive.

Adjacent docs

  • multi-ticket.md — defines state.toml schema and the workflow that consumes [status_labels].
  • ticket-rag.md — defines the [rag] namespace's runtime semantics.
  • ticket-gh-init.md — the skill that writes .project-conf.toml for new GitHub-backed projects.

Clone this wiki locally