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
11 changes: 6 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -140,11 +140,11 @@ In this repository, each house opinion is a marked block beside the sourced text

## Maintenance via skills

Agent skills maintain the repository, and two of them, `follow-opinions` and `review-project`, run on someone else's project. They follow the [Agent Skills specification](https://agentskills.io/specification), so any compliant agent can run them. Each skill is a directory under [`skills/`](skills) with a `SKILL.md` file.
Agent skills maintain the repository, and three of them, `follow-opinions`, `research-topic`, and `review-project`, run on someone else's project. They follow the [Agent Skills specification](https://agentskills.io/specification), so any compliant agent can run them. Each skill is a directory under [`skills/`](skills) with a `SKILL.md` file.

The skills split work by cost. Lower-cost worker agents run the web searches and source scans in parallel. The strongest available model is the editor, and only the editor writes to the opinions and templates.

Every skill that changes this repository works on its own branch, and its changes land through a pull request that passes CI, gets an agent review, and passes the maintainer's review. The three report-only skills change nothing, and `follow-opinions` writes only to the project it runs in. Each `SKILL.md` is canonical over this diagram.
Every skill that changes this repository works on its own branch, and its changes land through a pull request that passes CI, gets an agent review, and passes the maintainer's review. The three report-only skills in the diagram change nothing, `research-topic` only answers, and `follow-opinions` writes only to the project it runs in. Each `SKILL.md` is canonical over this diagram.

![Maintenance pipeline: each skill from what starts it, through CI checks, an agent review, and the maintainer's review, to the roster, research, or the opinions and templates; audit-freshness, review-opinions, and review-project only report](assets/diagrams/maintenance-pipeline.svg)

Expand All @@ -154,18 +154,19 @@ Every skill that changes this repository works on its own branch, and its change
| [`follow-opinions`](skills/follow-opinions/SKILL.md) | Apply the opinions and templates while writing or changing code in a project |
| [`harvest-sources`](skills/harvest-sources/SKILL.md) | Scan the awesome-humans sources for new posts, and add notable guidance to the opinions |
| [`refresh-dotnet-versions`](skills/refresh-dotnet-versions/SKILL.md) | Detect new .NET, C#, and F# releases, and update all opinions and templates to target them |
| [`research-topic`](skills/research-topic/SKILL.md) | Research a .NET topic from the opinions and vetted sources, and save it with citations |
| [`research-topic`](skills/research-topic/SKILL.md) | Answer a .NET question from the opinions and vetted sources, citing each claim |
| [`resolve-research`](skills/resolve-research/SKILL.md) | Resolve a saved research topic by weaving it into the opinions and templates, or discard it |
| [`review-opinions`](skills/review-opinions/SKILL.md) | Check that the opinions and templates agree with their cited sources and with each other |
| [`review-project`](skills/review-project/SKILL.md) | Check an external project against the opinions and templates, and report deviations |
| [`stage-research`](skills/stage-research/SKILL.md) | Research a .NET topic, and save it under `research/` with citations |
| [`vet-source`](skills/vet-source/SKILL.md) | Evaluate a candidate source against the track-record criteria and admit or decline |
| [`weave-house-opinion`](skills/weave-house-opinion/SKILL.md) | Weave a house profile's opinion into the opinions and templates, visibly marked as House |

### Research lifecycle

Research is staged, never merged in place. `research-topic` saves the evidence, and `resolve-research` decides what becomes an opinion and deletes the file in the same pull request. A topic on disk is unresolved. The two `SKILL.md` files are canonical over this diagram.
Research is staged, never merged in place. `stage-research` saves the evidence, and `resolve-research` decides what becomes an opinion and deletes the file in the same pull request. A topic on disk is unresolved. The two `SKILL.md` files are canonical over this diagram.

![Research lifecycle: research-topic saves a topic under research/, and resolve-research promotes, discards or partly promotes it](assets/diagrams/research-lifecycle.svg)
![Research lifecycle: stage-research saves a topic under research/, and resolve-research promotes, discards or partly promotes it](assets/diagrams/research-lifecycle.svg)

A part that waits on an unvetted source stays on disk. It goes back through `resolve-research` if `vet-source` admits the source, and is discarded if not.

Expand Down
2 changes: 1 addition & 1 deletion agents/maintaining.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
| `chore` | Dependencies and housekeeping |
| `research` | Staging or discarding a research topic (repository-only) |

A skill that sets its own title says so in its `SKILL.md`, as `research-topic` and `resolve-research` do.
A skill that sets its own title says so in its `SKILL.md`, as `stage-research` and `resolve-research` do.

- **Fill in the pull request template a skill names.** The templates are the organisation's, in [awesome-humans/.github: `PULL_REQUEST_TEMPLATE/`](https://github.com/awesome-humans/.github/tree/main/PULL_REQUEST_TEMPLATE), and each skill's "Open a pull request" step names its own. Fill in every section, and pass the result to `gh pr create --body-file`. If a section doesn't apply, write "Doesn't apply" and the reason, instead of deleting it. The description becomes the commit message, so follow [Writing style: Commit messages and pull requests](https://github.com/awesome-humans/website/blob/main/pages/conventions/writing-style.md#commit-messages-and-pull-requests). Delete the template's guidance comment, and leave out tables, checkboxes, and inline links. End with a `Closes: #<number>` or `Refs: #<number>` trailer for each related issue, written as `awesome-humans/<repository>#<number>` for an issue in another repository. A person opening a pull request in the browser gets the default template, which links the others.

Expand Down
4 changes: 2 additions & 2 deletions agents/metadata.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ sources: [andrew-lock, dotnet-blog] # ids from AWESOME-HUMANS.md, sorted
---
```

A `research/` topic has no status field. Promoting or discarding a topic deletes it, so a topic on disk is unresolved by definition, and a status could only ever read `open`. For details, see [research-topic](../skills/research-topic/SKILL.md) and [resolve-research](../skills/resolve-research/SKILL.md).
A `research/` topic has no status field. Promoting or discarding a topic deletes it, so a topic on disk is unresolved by definition, and a status could only ever read `open`. For details, see [stage-research](../skills/stage-research/SKILL.md) and [resolve-research](../skills/resolve-research/SKILL.md).

**`templates/` use a first-line comment header.** An XML, INI, or source file can't open with a `---` block and stay valid for the tools that read it. So the same fields go in a comment instead, separated by pipes after a fixed marker:

Expand All @@ -36,7 +36,7 @@ Rules:
- CI reads the `**Discovery-only.**` and `**Corroborate.**` markings from a source's section under `## Source notes`, not from its table row.
- In `opinions/` and `templates/`, the source must also be citable. A watch-list source or a `**Discovery-only.**` source is rejected.
- A file whose citable sources are all marked `**Corroborate.**` is rejected too, because an unmarked source has to stand beside them.
- `research/` is exempt: a topic can cite unvetted material if the text flags it. For details, see [research-topic](../skills/research-topic/SKILL.md).
- `research/` is exempt: a topic can cite unvetted material if the text flags it. For details, see [stage-research](../skills/stage-research/SKILL.md).
- **Sort `sources` by ID in ordinal order, with `house:<profile>` sorted like any other ID.** Write `[andrew-lock, dotnet-blog, house:simon-mckenna, ms-learn]`. The rule applies in all three directories and to both syntaxes.
- **Write dates in ISO 8601 (`YYYY-MM-DD`), in UTC.** Always use absolute dates, never relative ones. To get today's date, run `date -u +%F`. CI, GitHub, and the site build run in UTC, as [awesome-humans/website: Writing style](https://github.com/awesome-humans/website/blob/main/pages/conventions/writing-style.md) describes.
- **Two template files are exempt from the header:** `templates/global.json` and `templates/example.slnf`, because JSON has no comment syntax. What they pin is audited against the latest releases instead. Smoke-testing the example projects by hand leaves build output under `templates/` (`artifacts/`, `bin/`, and `obj/`, all gitignored). That output isn't a resource, and the check skips it.
Expand Down
Loading
Loading