Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 10 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,14 +62,20 @@ agentsync doctor # what has drifted

Run without `--apply` first to see what a command would do.

For Claude project skills, put a directory such as `skills/release-check/SKILL.md`
in the canonical checkout. Run `agentsync link --skill release-check` from the
project to preview the link, then add `--apply`. Use
`agentsync import --skill release-check` to preview capturing an existing
project skill and its support files. [Project skills](docs/skills.md)

## Commands

| Command | Does |
|---|---|
| `init` | find your agents repo and write the config file |
| `scan` | classify project agents against the canonical repo (read-only) |
| `import` | capture project-only agents into `project-agents/` |
| `link` | replace project agent files with symlinks into the canonical repo |
| `scan` | classify project agents and skills against the canonical repo (read-only) |
| `import` | capture project-only agents or selected skill directories |
| `link` | provision project agents and selected skills from the canonical repo |
| `doctor` | report broken, foreign, or mismatched links and stale captures; never writes |
| `reconcile` | act on that drift, gated on what agentsync itself recorded |
| `inventory` | regenerate `inventory.json`, a record of every agent on the machine |
Expand All @@ -85,6 +91,7 @@ Run without `--apply` first to see what a command would do.
- [scan](docs/scan.md)
- [import](docs/import.md)
- [link](docs/link.md)
- [Project skills](docs/skills.md)
- [doctor](docs/doctor.md)
- [reconcile](docs/reconcile.md)
- [inventory](docs/inventory.md)
Expand Down
28 changes: 20 additions & 8 deletions cmd/agentsync/doctor.go
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import (

"github.com/agentic-tooling/agentsync/internal/doctor"
"github.com/agentic-tooling/agentsync/internal/scan"
"github.com/agentic-tooling/agentsync/internal/skills"
)

// runDoctor reports the ways this repo and the projects it serves have drifted
Expand Down Expand Up @@ -64,13 +65,20 @@ func runDoctor(args []string, stdout, stderr io.Writer) int {
return exitFailure
}

skillReport, err := scanSkills(repo, res.SkillDirs)
if err != nil {
fmt.Fprintf(stderr, "agentsync: %v\n", err)
return exitFailure
}
dirs := append(res.Dirs, skillReport.Dirs...)
run := doctorRun{
repoRoot: repo.Root,
root: root.Path,
home: repo.Home,
res: res,
check: repo.CheckHome(root.Path, res.Dirs),
check: repo.CheckHome(root.Path, dirs),
report: doctor.Diagnose(repo, res),
skills: skillReport,
}
findings, problems := overrideFindings(repo.Home, res.Dirs)
run.report.Findings = append(run.report.Findings, findings...)
Expand All @@ -85,7 +93,7 @@ func runDoctor(args []string, stdout, stderr io.Writer) int {
// projects the scan walked, HomeWarning judges the capture keys nothing
// walked, and the reproduction that made this necessary is precisely the
// run where the first has nothing to say and the second has everything.
warnHome(stderr, repo, root.Path, res.Dirs, *allowOutsideHome)
warnHome(stderr, repo, root.Path, dirs, *allowOutsideHome)
if warning := run.report.HomeWarning(repo.Home); warning != "" {
fmt.Fprintf(stderr, "agentsync: warning: %s\n", warning)
}
Expand Down Expand Up @@ -114,6 +122,7 @@ type doctorRun struct {
res scan.Result
check scan.HomeCheck
report doctor.Report
skills skills.Report
}

// exitCode maps the run onto the CLI contract.
Expand All @@ -132,10 +141,10 @@ type doctorRun struct {
// A foreign link never affects the code, in either direction. It is reported and
// it is not a fault.
func (r doctorRun) exitCode() int {
if len(r.report.Problems) > 0 {
if len(r.report.Problems)+len(r.skills.Problems) > 0 {
return exitFailure
}
if len(r.report.NeedsHuman()) > 0 || len(r.res.Problems) > 0 {
if len(r.report.NeedsHuman())+len(r.res.Problems)+len(r.skills.AtRisk().Entries) > 0 {
return exitAtRisk
}
return exitOK
Expand All @@ -144,7 +153,7 @@ func (r doctorRun) exitCode() int {
// incomplete reports whether the scan failed to look at part of the tree, which
// disqualifies the summary from claiming everything lines up.
func (r doctorRun) incomplete() bool {
return len(r.res.Problems) > 0 || len(r.report.Problems) > 0
return len(r.res.Problems)+len(r.report.Problems)+len(r.skills.Problems) > 0
}

// doctorHome is the home-directory signal in machine-readable form.
Expand Down Expand Up @@ -179,6 +188,7 @@ type doctorHome struct {

// doctorReport is the --json form.
type doctorReport struct {
skills.Report
Repo string `json:"repo"`
Root string `json:"root"`
Home doctorHome `json:"home"`
Expand All @@ -195,8 +205,9 @@ type doctorReport struct {

func (r doctorRun) emitJSON(w io.Writer) error {
rep := doctorReport{
Repo: r.repoRoot,
Root: r.root,
Report: r.skills,
Repo: r.repoRoot,
Root: r.root,
Home: doctorHome{
Status: r.check.Status.String(),
Path: r.check.Home,
Expand Down Expand Up @@ -264,6 +275,7 @@ func (r doctorRun) emitText(w io.Writer) {
}

emitDoctorProblems(w, r.report.Problems, r.res.Problems)
emitSkills(w, r.skills)

fmt.Fprintln(w, strings.Repeat("-", 60))
r.emitSummary(w)
Expand All @@ -281,7 +293,7 @@ func (r doctorRun) emitSummary(w io.Writer) {
// project's own git tracks, and on a --project key that names nothing.
// None of those is drift, none is doctor's to find, and a summary that
// read like an all-clear for the whole toolchain would be relied on as one.
switch n := len(r.report.NeedsHuman()); {
switch n := len(r.report.NeedsHuman()) + len(r.skills.AtRisk().Entries); {
case n == 0 && !r.incomplete():
fmt.Fprintln(w, "Nothing has drifted: every link resolves to its counterpart and every capture has a live file.")
fmt.Fprintln(w, "That is a statement about drift only — whether `link` would run clean is its own question, and `agentsync link` answers it.")
Expand Down
22 changes: 22 additions & 0 deletions cmd/agentsync/import.go
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import (

"github.com/agentic-tooling/agentsync/internal/importer"
"github.com/agentic-tooling/agentsync/internal/scan"
"github.com/agentic-tooling/agentsync/internal/skills"
)

// runImport captures project-only agent files into the repo.
Expand All @@ -31,6 +32,8 @@ func runImport(args []string, stdout, stderr io.Writer) int {
all := registerAll(fs)
apply := fs.Bool("apply", false, "write the captures; without it this is a dry run")
var update updateFlag
var skillNames stringList
fs.Var(&skillNames, skills.Flag, "capture a project skill directory (repeatable)")
fs.Var(&update, "update",
"replace a captured copy whose content differs; --update=<project>/<name> for one, repeatable")
includeTracked := fs.Bool("include-tracked", false,
Expand Down Expand Up @@ -78,6 +81,25 @@ func runImport(args []string, stdout, stderr io.Writer) int {
return exitFailure
}

if len(skillNames) > 0 {
if err := skills.ValidateNames(skillNames); err != nil {
fmt.Fprintf(stderr, "agentsync: %v\n", err)
return exitFailure
}
if update.set.Enabled() {
fmt.Fprintln(stderr, "agentsync: --update applies to agent captures; skill captures are write-once")
return exitFailure
}
var keys []string
if root.Project != "" {
keys = []string{root.Project}
}
return (skillRun{
mode: skills.Import, apply: *apply, allowOutsideHome: *allowOutsideHome,
asJSON: *asJSON, failOnPending: *failOnPending, keys: keys, names: skillNames,
}).run(repo, repoFrom, root, stdout, stderr)
}

res, err := repo.Scan(root.Path)
if err != nil {
fmt.Fprintf(stderr, "agentsync: %v\n", err)
Expand Down
38 changes: 36 additions & 2 deletions cmd/agentsync/link.go
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import (

"github.com/agentic-tooling/agentsync/internal/linker"
"github.com/agentic-tooling/agentsync/internal/scan"
"github.com/agentic-tooling/agentsync/internal/skills"
"github.com/agentic-tooling/agentsync/internal/state"
)

Expand Down Expand Up @@ -143,8 +144,9 @@ func runLink(args []string, stdout, stderr io.Writer) int {
allowOutsideHome := fs.Bool(scan.AllowOutsideHomeFlag, false,
"projects legitimately live outside $HOME; permit the write anyway")

var projects, agents stringList
var projects, agents, skillNames stringList
fs.Var(&projects, linker.ProjectFlag, "restrict to this project key (repeatable)")
fs.Var(&skillNames, skills.Flag, "link a project skill directory (repeatable)")
fs.Var(&agents, linker.AgentFlag,
"also link this agent into the selected projects even if absent (repeatable; requires --"+linker.ProjectFlag+")")

Expand Down Expand Up @@ -197,6 +199,18 @@ func runLink(args []string, stdout, stderr io.Writer) int {
if len(opts.Projects) == 0 && root.Project != "" {
opts.Projects = []string{root.Project}
}
if err := skills.ValidateNames(skillNames); err != nil {
fmt.Fprintf(stderr, "agentsync: %v\n", err)
return exitFailure
}
skill := skillRun{
mode: skills.Link, apply: *apply, excludeLocal: *excludeLocal,
allowOutsideHome: *allowOutsideHome, asJSON: *asJSON,
keys: opts.Projects, names: skillNames,
}
if len(skillNames) > 0 && len(agents)+len(undecline.keys) == 0 {
return skill.run(repo, repoFrom, root, stdout, stderr)
}
if err := opts.Validate(); err != nil {
fmt.Fprintf(stderr, "agentsync: %v\n", err)
// The root is *why* no project was selected, and saying so is what
Expand Down Expand Up @@ -255,13 +269,25 @@ func runLink(args []string, stdout, stderr io.Writer) int {
cleared: cleared,
unmatched: unmatched,
}
var catalog *skills.Catalog
if len(skillNames) > 0 {
catalog, run.skills, _, err = skill.prepare(repo, root)
if err != nil {
fmt.Fprintf(stderr, "agentsync: %v\n", err)
return exitFailure
}
defer func() { _ = catalog.Close() }()
}
if run.apply {
run.done, run.errs = plan.Apply(repo, st)
// Save clears Dirty only on success, so a dirty document means the
// cleared markers are still on disk.
if st.Dirty() {
run.cleared, run.uncleared = nil, run.cleared
}
if catalog != nil {
catalog.Apply(run.skills, *excludeLocal)
}
}

emitRepoChoice(reportStream(*asJSON, stdout, stderr), repo, repoFrom)
Expand All @@ -281,8 +307,10 @@ func runLink(args []string, stdout, stderr io.Writer) int {
// really appeared. Excludes and state records change nothing a session
// loads, so neither earns this line.
emitRestartNotice(reportStream(*asJSON, stdout, stderr), len(run.done.Links) > 0)
_, written, blocked, failed := run.skills.Counts()
emitSkillRestart(reportStream(*asJSON, stdout, stderr), written)

return run.exitCode()
return max(run.exitCode(), skillExitCode(0, blocked, failed, false))
}

// linkRun is one invocation: what was planned, what was written, and what went
Expand All @@ -297,6 +325,7 @@ type linkRun struct {
plan linker.Plan
done linker.Applied
errs []error
skills skills.Plan

// statePath is where the run's records go, named in the report because
// people go and look at this file by hand.
Expand Down Expand Up @@ -352,6 +381,7 @@ func (r linkRun) linkCaveat() string {
// linkReport is the --json form. It reports the whole plan, not just the
// writes: what was refused and why is the part a user cannot reconstruct.
type linkReport struct {
SkillActions skills.Plan `json:"skill_actions,omitempty"`
Apply bool `json:"apply"`
ExcludeLocal bool `json:"exclude_local"`
Repo string `json:"repo"`
Expand Down Expand Up @@ -388,6 +418,7 @@ type linkReport struct {

func (r linkRun) emitJSON(w io.Writer) error {
rep := linkReport{
SkillActions: r.skills,
Apply: r.apply,
ExcludeLocal: r.opts.ExcludeLocal,
Repo: r.repoRoot,
Expand Down Expand Up @@ -530,6 +561,9 @@ func (r linkRun) emitText(w io.Writer) {

fmt.Fprintln(w, strings.Repeat("-", 60))
r.emitSummary(w)
if len(r.skills) > 0 {
emitSkillActions(w, r.skills, r.apply)
}
}

func (r linkRun) emitSummary(w io.Writer) {
Expand Down
Loading