Ship the agentic layer as an agd kit

Open
  • Is something wrong?
#88 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
52/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
github, python
Domain
developer-experience, tooling

Research direction

Start by reading the repository’s existing agentic installation instructions and the agd guides linked in the issue, then inspect the skill directories and .github/agents/living-doc-bdd-copilot.agent.md to map them into the requested packs. Create root packs.txt and update agentic/README.md and release notes; validate with agd check, both scratch-project install commands, and npx skills add ... --list. Done when all seven acceptance criteria pass.

Written by the indexing model from the issue text.

Description

type:feature
Feature Description

Make the agentic layer installable with agd, next to the current skills CLI install:

  • in a project: agd init AbsaOSS/living-doc --with bdd
  • for one person, in every project on their machine: agd --home init AbsaOSS/living-doc --with entities,bdd,pageobject

This starts after the first living-doc release, so the kit has a release tag to pin. #87 settles the names and paths before that release, so this change is additive and breaks nothing.

Problem / Opportunity

Today an author runs 13 separate npx skills add commands, remembers that the shared skill is required, and copies the agent by hand. Nothing records which version a project has, and an update reaches a project without review.

agd gives:

  • a versioned .agd.lock;
  • packs with requires, so the shared skill comes along on its own;
  • updates as a reviewed PR, through the weekly workflow the living-doc repositories already run;
  • a stop when a release tag moves;
  • a kept ## This project section, so a project can add to a skill without losing it on update.
Acceptance Criteria
  1. packs.txt at the repository root has root agentic and these packs:
    • shared: .claude/skills/living-doc-shared/
    • entities: create-user-story, create-feature, create-functionality, update, gap-finder, impact-analysis
    • bdd: gherkin-step, gherkin-living-doc-sync, bdd-maintain, scenario-creator
    • pageobject: pageobject-scan, data-cy-instrument
    • copilot-agent: .github/agents/living-doc-bdd-copilot.agent.md, which needs the three skill packs
    • every skill pack requires shared
  2. agd check passes with no errors on the release that adds packs.txt. It warns about the agent's tools: line, which a Copilot agent needs: accept the warning.
  3. In a scratch project, agd init AbsaOSS/living-doc --with bdd installs the bdd skills and living-doc-shared, and the skills' bundled scripts run, including their import of the shared library.
  4. HOME=<scratch> agd --home init AbsaOSS/living-doc --with entities,bdd,pageobject installs without a stop. copilot-agent is only for projects: agd installs nothing outside .claude/ in a home folder.
  5. npx skills add https://github.com/AbsaOSS/living-doc --list still lists every skill, so both install paths keep working.
  6. agentic/README.md makes agd the main install path, keeps the skills CLI as an alternative, and shows how an existing skills CLI install moves over (Move from skills.sh: npx skills remove for linked skills, agd adopt for real copies).
  7. The release notes list the agentic layer's changes and any manual steps for projects.
Proposed Solution
  • Versions: kit releases are living-doc release tags. agd reads only v<major.minor.patch> tags, so if living-doc tags another way, decide that first. With one tag namespace, every release's notes must cover the agentic layer too. Between releases, early adopters can follow master with agd init … --latest.
  • Out of agd's reach: Python 3.10+ with PyYAML and jsonschema in an activated venv, and a Playwright MCP server for pageobject-scan. They stay in the README.
  • The kit-authoring skill from agentic-home (agd --home init) can help an agent write packs.txt and run agd check.
Dependencies / Related
Dominant language
Python
Stars
0
Forks
0
Avg merge
6h 14m
Merged PRs (30d)
27

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from AbsaOSS/living-doc

All issues in AbsaOSS/living-doc

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.