feat: 7 - living doc copilot

.github/agents/evals/living-doc-bdd-copilot/fixture-map.md

@@ -0,0 +1,27 @@
+# Fixture Map — living-doc-bdd-copilot agent evals
+
+## Eval coverage summary
+
+| Eval ID | Category | Description | Fixture files |
+|---------|----------|-------------|---------------|
+| 1 | happy-path | Business Seed assembly — seed.yaml structure | — |
+| 2 | happy-path | Create mode: PageObject generation from crawled surface | — |
+| 3 | happy-path | Scenario generation from US ACs | — |
+| 4 | regression | RE-SCAN mode — selector drift detection and repair | — |
+| 5 | regression | HEALING mode — broken step definitions | — |
+| 6 | negative | Unit test request → @sdet-copilot | — |
+| 7 | paraphrase | "fix failing tests" → HEALING mode trigger | — |
+| 8 | regression | REMOVE mode — full feature removal with pre-deletion checklist | — |
+| 9 | regression | Partial state rule: seed.yaml present, manifest.json absent → first run | — |
+| 10 | regression | Credential safety — literal credentials in seed.yaml rejected | — |
+| 11 | edge-case | Source E guided traversal — blocked crawl, unknown field value | — |
+| 12 | output-format | manifest.json entry structure for a scanned route | — |
+| 25 | negative | Unit test request → decline + direct to @sdet-copilot | — |
+
+## Trigger eval summary
+
+| Count | Triggers (should_trigger=true) | Non-triggers (should_trigger=false) |
+|-------|-------------------------------|--------------------------------------|
+| 44 total | 22 true | 22 false |
+
+> No fixture files — all evals use inline prompt/expected_output; agent behavior is assessed against the agent.md operating rules and skill definitions.

.github/copilot-instructions.md

@@ -1,5 +1,13 @@
 # Copilot Instructions
 
+## Always Active
+
+The **token-saving** skill is always active in this workspace. Every response applies concise formatting rules and removes noise (no filler, no closing platitudes, structured output). 
+
+See [Token-Saving Skill](../docs/guides/token-saving.md) for details, including override behavior when you explicitly request depth.
+
+---
+
 ## PR Review
 
 When reviewing a pull request, load and apply:

.gitignore

@@ -0,0 +1,5 @@
+**/__pycache__/*
+**/.DS_Store
+skills-eval-workspace/*
+agents-eval-workspace/*
+.playwright-mcp/*

CONTRIBUTING.md

@@ -38,8 +38,14 @@ skills/
 | `scripts/`    | Deterministic or repetitive logic better run as code than described in prose (e.g. a validation script, a formatter, a data transformer) |
 | `references/` | Domain docs, API specs, decision tables, or anything too large to keep in `SKILL.md` without exceeding 500 lines                         |
 | `assets/`     | Template files, example inputs/outputs, icons — anything the skill produces or consumes                                                  |
-| `evals/`      | Test prompts and assertions to verify skill behavior and trigger accuracy. See [skill-testing.md](./docs/skill-testing.md)               |
+| `evals/`      | Test prompts and assertions to verify skill behavior and trigger accuracy. See [skill-testing.md](./docs/testing/skill-testing.md)               |
 
+#### `references/` — shared vs. skill-specific
+
+- **`skills/<skill>/references/`** — skill-specific docs loaded only by that skill's instructions
+- **`skills/shared/references/`** — shared docs used by multiple skills (e.g., schemas, glossaries, common API specs)
+
+If a reference file is used by 2+ skills, place it in `skills/shared/references/` instead of duplicating it. See [living-doc-bdd-schemas.md](skills/shared/references/living-doc-bdd-schemas.md) and [living-doc-glossary.md](skills/shared/references/living-doc-glossary.md) for examples.
 ---
 
 ## 2. Frontmatter schema
@@ -177,6 +183,21 @@ should be run") — it is clearer and easier for the agent to follow.
 
 If every test run of your skill independently writes the same helper script (a formatter, a validator, a transformer), bundle it in `scripts/` and reference it from `SKILL.md`. This saves every future invocation from reinventing the wheel.
 
+### Shared utilities and assets across multiple skills
+
+**Pattern:** If code, references, or assets are used by 2+ skills, place them in `skills/shared/`:
+
+- **`skills/shared/lib/`** for shared Python modules → each skill has a wrapper
+- **`skills/shared/references/`** for shared documentation → skills link directly
+- **`skills/shared/assets/`** for shared templates/data → skills reference relative paths
+
+Examples:
+- `skills/shared/lib/living_doc_id.py` — shared by three living-doc skills
+- `skills/shared/references/living-doc-glossary.md` — shared by multiple living-doc skills
+- See [skills/shared/lib/README.md](skills/shared/lib/README.md) for implementation details
+
+**Benefits:** Single source of truth, prevents drift, easier maintenance, each skill remains independently deployable.
+
 ### Format conventions
 
 - Use `##` and `###` headings to structure the body
@@ -201,7 +222,7 @@ If every test run of your skill independently writes the same helper script (a f
 Before proposing a PR, verify that your skill activates correctly and produces good output. The full testing
 methodology — eval creation, fixture management, with/without comparisons, trigger testing, and description
 optimization using the Anthropic [`skill-creator`](https://github.com/anthropics/skills/tree/main/skills/skill-creator)
-skill — is covered in **[docs/skill-testing.md](./docs/skill-testing.md)**.
+skill — is covered in **[docs/testing/skill-testing.md](./docs/testing/skill-testing.md)**.
 
 ---
 

README.md

@@ -77,9 +77,31 @@ its purpose, trigger phrases, and full instructions.
 
 | Skill                                                | Description                                                                                                                         |
 |------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
+| **[living-doc-create-user-story](./skills/living-doc-create-user-story/)** | Create a well-formed User Story with business-level Acceptance Criteria that are traceable, testable, and E2E-ready. |
+| **[living-doc-create-feature](./skills/living-doc-create-feature/)** | Document a system surface (UI screen, API endpoint, service) as a Feature entity with ownership and traceability links. |
+| **[living-doc-create-functionality](./skills/living-doc-create-functionality/)** | Define an atomic, testable behaviour (Functionality) with AC designed for fast unit or integration tests. |
+| **[living-doc-update](./skills/living-doc-update/)** | Amend or deprecate existing User Story, Feature, or Functionality entities — add ACs, change status, update ownership. |
+| **[living-doc-impact-analysis](./skills/living-doc-impact-analysis/)** | Trace which Features, Functionalities, User Stories, and Gherkin scenarios are affected by a code change or PR. |
+| **[living-doc-gap-finder](./skills/living-doc-gap-finder/)** | Identify undocumented behaviours, orphan tests, and untested ACs. Used by `@living-doc-bdd-copilot` top-down (catalog gaps) and bottom-up (scenario coverage). |
+| **[living-doc-pageobject-scan](./skills/living-doc-pageobject-scan/)** | Discover, create, and maintain PageObject classes from a live web application — bootstrapping from scratch and detecting selector drift after UI changes. |
+| **[bdd-maintain](./skills/bdd-maintain/)** | REMOVE and DEAD CODE AUDIT modes — delete feature files, step definitions, and PageObjects linked to deprecated entities; audit unused steps and PageObject methods. |
+| **[data-cy-instrument](./skills/data-cy-instrument/)** | Resolve missing `data-cy` attributes in Angular component templates and sync PageObjects to use `getByTestId()` — run after a crawl when `coverage_gaps` are non-empty. |
+| **[living-doc-scenario-creator](./skills/living-doc-scenario-creator/)** | Generate full Gherkin feature files from User Story and Functionality ACs — feature file header, @AC:-tagged scenarios, complete Given/When/Then step bodies, coverage report, and step definition resolution. |
+| **[gherkin-step](./skills/gherkin-step/)** | Implement clean, reusable step definitions — behave (Python), Cucumber (Java, TypeScript, Scala), parameter types, DataTable, DocString, and hooks. |
+| **[gherkin-living-doc-sync](./skills/gherkin-living-doc-sync/)** | Synchronise Gherkin feature files with the living documentation catalog — fix missing AC traceability headers, step text drift, and stale scenario links. |
 | **[pr-review](./skills/pr-review/)**                 | Pull request code review — reviews diffs for risk, security issues, API contract changes, dependency bumps, CI/CD and infrastructure changes. Produces concise Blocker / Important / Nit comments. |
 | **[token-saving](./skills/token-saving/)**           | Always-active response discipline — enforces brevity, no filler openers or closers, structured output, and a What/Why/How footer on code responses. Suspends on explicit "full detail" requests. |
 
+## Agent Roster
+
+Agents are pre-configured AI personas that orchestrate multiple skills for a specific engineering phase. Agent files live in **[.github/agents/](./.github/agents/)**.
+
+
+
+| Agent | Description |
+|---|---|
+| **[@living-doc-bdd-copilot](./.github/agents/living-doc-bdd-copilot.agent.md)** | Living documentation and BDD automation — catalog management (User Stories, Features, Functionalities, AC updates, impact analysis, gap finding) and automation (webapp exploration, PageObjects, Gherkin scenarios, step definitions, BDD suite maintenance). |
+
 ## Finding More Skills
 
 Before building a new skill, check whether one already exists:
@@ -89,11 +111,13 @@ Before building a new skill, check whether one already exists:
 | [github/awesome-copilot](https://github.com/github/awesome-copilot/tree/main/skills) | 200+ community skills: cloud, languages, security, DevOps, productivity |
 | [skills.sh](https://skills.sh)                                                       | Open registry — install with `npx skills add <owner/repo>`              |
 | [anthropics/skills](https://github.com/anthropics/skills)                            | Anthropic reference skills including `skill-creator`                    |
+| [absa-group/agent-skills](https://github.com/absa-group/agent-skills)                | Broader ABSA-owned skill collection                                     |
+| [absa-group/cps-agentic-toolkit](https://github.com/absa-group/cps-agentic-toolkit)  | CPS team's extended skill set (ABSA-internal)                           |
 
 ## Contributing
 
 See **[CONTRIBUTING.md](./CONTRIBUTING.md)** for the skill authoring guide — folder layout, frontmatter schema, writing
-effective descriptions and bodies, [testing](./docs/skill-testing.md), and the PR checklist.
+effective descriptions and bodies, [testing](./docs/testing/skill-testing.md), and the PR checklist.
 
 To propose a new skill — or to propose expanding the repo into agents, MCP servers, or
 plugins — [open an issue](https://github.com/AbsaOSS/agentic-toolkit/issues/new).

docs/README.md

@@ -2,14 +2,24 @@
 
 Navigation hub for all guides in this repository. Browse by category below.
 
+## Contents
+
+- [Setup & Repository Guides](#setup--repository-guides)
+- [Tools for Agentic Development](#tools-for-agentic-development)
+- [Skill Guides](#skill-guides)
+- [Agent Guides](#agent-guides)
+
 ## Setup & Repository Guides
 
-| Guide | Description |
-|----|----|
-| [Getting Started](./getting-started.md) | What skills are, how to install them, Copilot CLI usage |
+| Guide                                   | Description                                                                         |
+|-----------------------------------------|-------------------------------------------------------------------------------------|
+| [Getting Started](./getting-started.md) | What skills are, how to install them, Copilot CLI usage                             |
 | [Contributing](../CONTRIBUTING.md)  | Skill folder layout, frontmatter, description writing, body guidelines, PR process |
-| [Skill Testing](./skill-testing.md) | Eval creation, fixtures, regression loops, trigger and description optimization |
-| [Troubleshooting](./troubleshooting.md) | Setup fixes for install, activation, and proxy issues |
+| [Responsible Agent Use](./responsible-agent-use.md) | Not burning your Copilot token budget — context, models, agent mode, MCP, plugins, skills, and a must-do checklist |
+| [Agent Design Best Practices](./guides/agent-design.md) | Core principles, file structure, context management, tool guidance, examples, and stopping conditions for `.agent.md` files |
+| [Skill Testing](./testing/skill-testing.md) | Eval creation, fixtures, regression loops, trigger and description optimization    |
+| [Agent Testing](./testing/agent-testing.md) | Eval creation and body quality testing for `.agent.md` files — agents are invoked by @-mention, not auto-triggered |
+| [Troubleshooting](./troubleshooting.md) | Setup fixes for install, activation, and proxy issues                               |
 
 ## Tools for Agentic Development
 
@@ -22,11 +32,16 @@ Navigation hub for all guides in this repository. Browse by category below.
 
 ## Skill Guides
 
-| Guide | Description |
-|----|----|
+| Guide                               | Description                                                                        |
+|-------------------------------------|------------------------------------------------------------------------------------|
 | [PR Review](./pr-review.md)             | How the PR review skill works, what sections it applies, and how to trigger it     |
-| [Token Saving](./token-saving.md)       | Keeping AI responses concise — how the token-saving skill works and when it applies |
-| [Responsible Agent Use](./responsible-agent-use.md) | Not burning your Copilot token budget — context, models, agent mode, MCP, plugins, skills, and a must-do checklist |
+| [Token Saving](./guides/token-saving.md)       | Keeping AI responses concise — how the token-saving skill works and when it applies |
+
+## Agent Guides
+
+| Guide                                         | Description                                                                              |
+|-----------------------------------------------|-------------------------------------------------------------------------|
+| [Living Doc BDD Copilot](./guides/living-doc-bdd-copilot.md) | Living documentation and BDD automation — catalog management (User Stories, Features, Functionalities, AC updates, impact analysis, gap finding) and automation (webapp exploration, PageObjects, Gherkin, step definitions, maintenance) |
 
 > **Keep this index up to date.** When you add a new guide, add a row to the appropriate table above.
 

docs/getting-started.md

@@ -141,6 +141,55 @@ your-project-repo/
             └── SKILL.md
 ```
 
+## Install Agents
+
+Agents are pre-configured AI personas that orchestrate multiple skills for a specific engineering phase. Unlike skills (which are auto-activated by description matching), agents are invoked explicitly by name in Copilot Chat.
+
+### How agents differ from skills
+
+| | Skills | Agents |
+|---|---|---|
+| Activation | Auto — triggered when your prompt matches the description | Manual — you @-mention the agent name |
+| Scope | Any compatible tool (Copilot, Claude, Cursor) | GitHub Copilot Chat (VS Code) |
+| Install location | `~/.agents/skills/` or `.github/skills/` | `.github/agents/` inside your project repo |
+
+### Install an agent into your project
+
+Copy the agent file into your project's `.github/agents/` directory:
+
+```bash
+# One-time setup
+mkdir -p .github/agents
+
+# Copy the agent
+cp path/to/agentic-toolkit/.github/agents/living-doc-bdd-copilot.agent.md .github/agents/
+```
+
+Or clone the toolkit and copy all agents:
+
+```bash
+git clone https://github.com/AbsaOSS/agentic-toolkit.git
+cp agentic-toolkit/.github/agents/*.agent.md .github/agents/
+```
+
+Commit the `.github/agents/` directory to share the agents with your team.
+
+### Use an agent in Copilot Chat
+
+Open Copilot Chat in VS Code and type `@` followed by the agent name:
+
+```
+@living-doc-bdd-copilot create user story for the login feature
+@living-doc-bdd-copilot living doc gaps
+@living-doc-bdd-copilot HEALING mode
+```
+
+The agent loads its skills on demand and follows its defined scope. 
+
+> ⚠️ **Agents are invoked only via `@-mention`** — the `description` field in an agent file is for documentation only, not an activation trigger (unlike skills). Type `@agent-name` explicitly in Copilot Chat to invoke the agent.
+
+See the [Agent Roster](../README.md#agent-roster) for the full list of available agents and their guides.
+
 ## Troubleshooting
 
 Running into issues? See **[docs/troubleshooting.md](./troubleshooting.md)** guide.