Overhaul agent skills, project docs, and planning infrastructure#19
Merged
Conversation
Apparently Anthropic claim the latest models are fully capable of writing good skills natively.
It's now project-specific (cross-project requires a different approach), and self-validates with the help of plan reviewers - arch and risks. It works by creating a main plan and sub plans, where each subplan is self-contained and is so simple that every agent could execute it. The subplans are reviewed by local agents as they require more context that depends on the project, the domain, and what the plan does.
It was good but no longer fits my planning vision.
It instructs it when to use agent teams, as well as trying to guess which model would be best suited for each sub-plan. Agent teams should respect the recommended models.
These are used either manually or suggested by the feature planner when it detects gaps. The goal is to have projects fully documented across all different layers: domain, arch, processes, components to help both humans and agents get a better understanding of the project. For agents, this should dramatically decrease token usage as they won't have to re-explore the codebase every time they try to plan a work item, or at least the thing to explore would remain minimal and concentrated. The planner is also updated to use the docs-updater skill at the end of the plan execution to allow docs to breathe and always be up-to-date. The planner has also been renamed to follow naming best practices.
It used to reference it in the skill's description, but that only gets read when fronmatter is loaded, and helps the agent decide if the skill is necessay - It makes it impossible to load it later. Also, the wording was confusing, as this skill is complementary rather than conflicitng. Both should be used together.
It would be used to create local reviewer subagents, which are used by the feature-planning skill to review sub-plans as domain experts.
The cli-apps skill relates to Cobra, huh and such. The "tooling" breaks down into building, linting and testing, leaving no room for the agent to guess on how to do those things.
It should be able to cover all the different aspects of the installer project, by preloading the necessary skills and using them as its review guidance.
This is a lesson learned from creating the local installer reviewer. The preloaded skills contain all the actual domain knowledge, repeating it inside the agent would make it stale eventually, leading to bad results over time.
This documentation serves both humans and agents. It should be iterated on every major change.
All should use reference links when linking. Architecture & Process docs should include mermaid diagrams for humans. Domain docs should focus on "what and why", never the "how".
They were generated with a much earlier version of AI, and have become either stale, wrong, or unnecessary.
I don't like being vendor-specific.
The new workflows shouldn't need such reviews anyway.
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.
What
Major rework of agent skills, (sub)agents, and project documentation.
Skills
New global skills:
planning-project-features— redesigned with multi-agent review and sub-plan decomposition (replacesfeature-planning)developing-plan-reviewers— create project-specific plan reviewer agentsdocumenting-domain,documenting-architecture,documenting-business-processes,documenting-components— documentation layer skills with mermaid diagram guidance, reference-link convention, and proper domain/process separationupdating-documentation— surgical doc updates after code changesapplying-effective-go,applying-architecture-patterns— renamed to gerund conventionNew local skills:
building-go-binaries,linting-go-code,testing-go-code,developing-cli-apps— Go tooling skillstesting-interactive-gpg— expect script for GPG prompt automationRemoved:
Command Development(massive, unused)feature-planning(replaced byplanning-project-features)Agents
New local agents:
plan-installer-reviewer,plan-ci-reviewer,plan-zsh-reviewer— domain-specific plan reviewersNew global agents:
plan-architect-reviewer,plan-risk-reviewer— structural plan reviewRemoved:
code-architecture-reviewer,plan-reviewer(generic, replaced by specialized reviewers)Project Documentation
Created (
docs/):domain.md— work environment model, chezmoi data schema, package resolution, shell source strategyarchitecture.md+architecture-installer.md— system structure with mermaid diagramsDeleted (old Sonnet-generated files):
docs/INSTALLATION.md,RELEASING.md,.github/INSTALLER_CI_README.md,installer/README.md,installer/docker/README.mdConventions added to CLAUDE.md
dot_claude/, edit there not~/.claude/