Repository navigation
Keep the process skills and the backlog in the repository - #11
Merged
Merged
Conversation
The tasks, changelog, and tech-debt skills defined how work in tfscli is planned, how the changelog is written, and how deferred problems are recorded, yet they lived only in one developer's home directory. CLAUDE.md told an agent to ask when they were missing, and CONTRIBUTING.md kept a third copy of their rules as a summary. The three skills now live under .claude/skills/, so every contributor and every agent has the same rules. Each file is identical to its general version: it opens by deferring to a project copy when one exists and to the project's own documentation where that sets a different convention, so the choices left to tfscli are written in CONTRIBUTING.md rather than in the skills. The skills themselves changed in the process: - changelog uses all six Keep a Changelog sections, names a versioning scheme in the preamble only when the project declares one, and leaves an existing changelog in another format unconverted unless asked. - tech-debt closes an entry as fixed, with a reference, or as dropped, with a reason - the practice docs/tech-debt.md had already adopted. - tasks places its files next to existing ones, then in the project's documentation directory, then in docs/. docs/tech-debt.md follows the new entry format and gets a proper title. The purpose of each project document is now written down where an editor meets it. CONTRIBUTING.md gains a map of the documents, what each records, and when it changes; project-brief.md and architecture.md state their purpose at the top. The brief records purpose, scope, constraints, non-goals, and design principles and changes only with a product decision; feature behaviour belongs in README.md. Its sections that describe current behaviour predate that rule and are recorded as TD-08. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QdgV5rygmGcBfQQBMtuQpt
The tasks skill worded its archive condition three ways, so a file whose last task was skipped could stay Active, and it sent an agent past a task left In progress by an interrupted session to the next Pending one. A task now counts as resolved when it is Done or Skipped, the file is archived once every task is resolved, and an unfinished task is resumed before a new one starts. The skill's invariant against assuming project files no longer contradicts its rule that project conventions win, mode detection no longer treats a request for new work as a request to continue the one active file, and a project whose tasks files are all archived keeps new ones beside the archive rather than in it. The tech-debt skill described adding an entry only during a review; it now covers any deliberate deferral and says which commit the entry goes into. A deferred bug is no longer excluded, and the closing remark no longer borrows "archived" from the tasks skill. The rest is wording: metaphors and a first-person placeholder in the skills, an unclear sentence in the changelog skill, two inaccuracies in the Process section of CONTRIBUTING.md, an ambiguous reference and an outdated list heading in CLAUDE.md, whose document descriptions now match the headers of the brief and the architecture, the header paragraphs written in the line style of their files, a time-bound "now" in TD-08, and a row for .claude/ in the top-level directories of architecture.md so that it is not confused with skills/. The skills under .claude/skills/ remain identical to their general versions. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QdgV5rygmGcBfQQBMtuQpt
Work accepted for later was kept as Active tasks files holding a single placeholder task to be broken down when its turn came. The tasks skill has no such stage: a breakdown made in advance goes stale, most of the effort before a start is discussion rather than tasks, and with several Active files its mode detection could never pick one on its own. A fourth process skill, backlog, now owns docs/backlog.md: accepted work in priority order, each entry carrying its goal, the decisions already made, and an optional trigger. The three API domains and the HTML quirks work move there, and their tasks files are removed; none had a resolved task. HTML quirks was the only file in the old format, so the exception for that format goes with it. The tasks skill now refuses to create a file for work that does not start now and points to wherever the project keeps planned work, without naming the backlog skill, which a user of tasks may not have. It also lets the plan change during execution: Pending tasks may be added, edited, reordered, or removed with the user's agreement, Done tasks are never rewritten, and task numbers are identifiers rather than order. The tech-debt format gains an optional Fix notes field, so that what is already known about a fix no longer has to be folded into the trigger; TD-07 and TD-08 are rewritten to use it. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Piji2RRZC6jeJ51vEorrNJ
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013xePd54F4w9BtuyAbVQUnD
The review read the skills as an agent would, literally, and found rules that contradict each other or leave a case uncovered. "Plan" meant both the breakdown of work that starts now and work kept for later. It now means only the breakdown; the backlog is "accepted work that has not started" everywhere, and "plan" is gone from the backlog skill's triggers. Its precondition field is renamed from Trigger to Blocked until, since a tech-debt Trigger makes a fix necessary while the backlog field only permits a start. The tasks skill now covers what the previous change left open: archiving when the last Pending tasks are removed rather than resolved, postponing an Active file (deleted when everything moves to the backlog, archived with its unresolved tasks skipped when it holds work already done), and a request for the next work when no Active file exists. Pending tasks may be renumbered to follow their order; Done and Skipped ones keep their numbers, since commits refer to them. The tech-debt skill sends accepted future work to the backlog, as the backlog skill already sends deferred problems to tech debt; shows an entry to the user before writing it and allows editing it, as the backlog does; says which commit closes an entry; and uses "entry" and `short-name` like the other skills. The changelog keeps the six Keep a Changelog sections. The four-section rule CONTRIBUTING.md used to state went away with the move into skills; "Choosing the version" now says that a Deprecated entry does not make a release breaking. The Process list there names each skill and its document only, since its summaries were what drifted from the skills. The ordering reason of the API domains is repeated in each domain entry of the backlog, so it survives when the first one starts. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Piji2RRZC6jeJ51vEorrNJ
Postponed work is accepted work that has not started, as the backlog defines it: once it stops, it counts as not started again. Renumbering Pending tasks keeps the numbers of Done, Skipped, and In progress tasks and never reuses one of them, so a Skipped task between Pending ones no longer causes a collision. The rule for deleting a postponed tasks file is stated without a double negative. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013xePd54F4w9BtuyAbVQUnD
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Moves the development process into the repository as four process skills and
reworks how planned work is kept.
.claude/skills/—tasks,backlog,changelog,tech-debt. They are the authoritative rules; CLAUDE.md and CONTRIBUTING.mdonly point to them and record the choices left to the project. Each skill
opens with "Project version first", so a personal copy defers to the
repository one.
docs/backlog.mdfor accepted work that has not started: goal,decisions already made, optional
Blocked until, priority by position.The placeholder tasks files for API domains 3–5 and
html-quirksmove thereand are deleted; the exception for the old tasks format goes with
html-quirks, its only user.tasksskillwherever the project keeps accepted work, without depending on the
backlogskill;edited, removed, and renumbered with the user's agreement; Done and
Skipped tasks are never rewritten;
tasks are removed.
tech-debtskill gains an optionalFix notesfield (TD-07 and TD-08now use it instead of overloading
Trigger), shows an entry before writingit, states which commit closes an entry, and sends new work to the backlog.
changelogskill allows all six Keep a Changelog sections; "Choosingthe version" states that a
Deprecatedentry does not make a releasebreaking.
project-brief.mdandarchitecture.md; CONTRIBUTING.md explains why the process lives inrepository files; references to the deleted tasks files now point to
docs/backlog.md.