diff --git a/CHANGELOG.md b/CHANGELOG.md index c74de34..2d10b63 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,11 @@ - No unreleased changes. +## [v1.4.0] + +- Rewrite the README as a front page: lead with what the skill gives you in plain language, then install and use, with technical and internal detail moved to the docs. +- Add `"license": "MIT"` to both plugin manifests and a top-level `"displayName"` to the Claude plugin manifest, after validating both manifests against the Claude Code and Codex plugin specs. + ## [v1.3.0] - Correct the standalone skill install locations to the Agent Skills standard. Use `.agents/skills/` as the cross-tool repository location (recognized by Codex and GitHub Copilot), `.claude/skills/` for Claude Code, and `.github/skills/` for GitHub Copilot. diff --git a/README.md b/README.md index 2977c1b..af6be53 100644 --- a/README.md +++ b/README.md @@ -1,86 +1,75 @@ # Postgres Introspection Skill -This repository packages an agent skill that teaches an AI coding agent to build a database introspection capability inside whatever repository it is working in. The skill is database-agnostic in method, with a runnable PostgreSQL reference implementation. +See your database clearly, keep the reasons behind it, and share both without a database or credentials. -## Install - -Most people do not need to clone this repository. Download the latest release from the [Releases page](https://github.com/TechSpokes/skill-postgres-introspection/releases) and install the asset that matches your tool. Every release attaches three ZIP files. After installing, ask your agent to set up database introspection in your repository. +This is an agent skill: a set of instructions an AI coding assistant loads to gain a new capability. This one teaches your assistant to read your database and write its current state into plain, readable files in your repository, and to record the reasons behind the design right next to the data. It is built for PostgreSQL and the method works for other databases too. -### Standalone skill +## What it gives you -This works with any agent that follows the Agent Skills standard. Download `postgres-introspection-vX.Y.Z.zip`, unzip it, and copy the `postgres-introspection/` folder into a skills directory in your repository: +A readable map of your database that stays current, so you and your AI tools stop piecing the truth together from migration files. -- `.agents/skills/` is the cross-tool standard location, recognized by Codex, GitHub Copilot, and other compatible tools, and scanned up to the repository root. Prefer this when several tools share one repository. -- `.claude/skills/` for Claude Code; use `~/.claude/skills/` for a personal install available in all projects. -- `.github/skills/` is also recognized by GitHub Copilot. +A picture you can share without access. Teammates and AI assistants can read, search, and review the schema with no running database and no credentials. -Keep the folder intact so `SKILL.md` can find its references. +The "why" kept with the data. The reasons behind a design live in the database itself as short comments, not scattered across documents that drift out of date. -### Claude Code plugin +A history you can follow. Because the files are regenerated as the database changes, each change shows up as a clean, reviewable diff over time. -Download `postgres-introspection-claude-plugin-vX.Y.Z.zip` and unzip it. The package contains `.claude-plugin/plugin.json` and the skill under `skills/`. Install it as a Claude Code plugin. +Safety by default. The skill tells the assistant to only read your database and to ask before anything that could affect your data. -### Codex plugin +## Install -Download `postgres-introspection-codex-plugin-vX.Y.Z.zip` and unzip it. The package contains `.codex-plugin/plugin.json` and the skill under `skills/`. Install it as a Codex plugin. +You do not need to clone this repository. Download the latest release from the [Releases page](https://github.com/TechSpokes/skill-postgres-introspection/releases) and install the piece that matches your tool. -For step-by-step details see [docs/INSTALL.md](docs/INSTALL.md), and for what to expect when you run it see [docs/QUICKSTART.md](docs/QUICKSTART.md). +### Standalone skill (works across tools) -## What introspection is +Download `postgres-introspection-vX.Y.Z.zip`, unzip it, and copy the `postgres-introspection/` folder into a skills directory in your repository: -Introspection is a read-only tool that reads a live database's catalogs and renders the current structure, security (row-level security, roles, grants), views, functions, and extensions into committed, navigable files. It is generated from the live database, not authored by hand, so it always reflects reality. +- `.agents/skills/` is the cross-tool standard location, recognized by Codex, GitHub Copilot, and other compatible tools. Prefer this when several tools share one repository. +- `.claude/skills/` for Claude Code; use `~/.claude/skills/` to install it for all your projects. +- `.github/skills/` is also recognized by GitHub Copilot. -It is distinct from two neighbors. Validation asserts that reality matches an expectation and answers yes or no. Documentation records intent and is written by a person. This skill builds introspection only. +Keep the folder intact so the skill can find its supporting files. -## Why it exists +### Claude Code plugin -The real state of a database-backed system lives in the database, yet it is hard to see: the authoritative record is usually a large dump and a history of migrations, and the architect's reasons behind the schema are not stored anywhere at all. This skill closes both gaps. It gives the repository a tool that exports the current state into files anyone can read, and a discipline for capturing the architect's intent as comments next to the data. +Download `postgres-introspection-claude-plugin-vX.Y.Z.zip`, unzip it, and install it as a Claude Code plugin. -The committed output has two properties that make it valuable. It is shareable offline: anyone can read, search, and diff the schema with no running database and no credentials, which lets teams and different AI agents reason about the database together. It is a time series: because the output is deterministic and stamped with the migration version, the git history becomes a reviewable record of how the database evolved. +### Codex plugin -## What the skill produces in a target repository +Download `postgres-introspection-codex-plugin-vX.Y.Z.zip`, unzip it, and install it as a Codex plugin. -A runnable introspection tool fitted to the repository's own stack, which keeps working after this skill is gone. +For step-by-step help, see [docs/INSTALL.md](docs/INSTALL.md). -Committed state files: a single navigable data file, a single complete document, and a per-object file per table, view, and function. +## Using it -Generation wired to the migration run, and an entry in the repository's agent instructions so future agents find the capability and read the state instead of reconstructing it. +Once installed, ask your assistant to set it up, for example: -## How a human drives it +```text +Set up database introspection in this repository. +``` -Ask an AI coding agent that has this skill to set up database introspection in your repository. Following the skill, the agent confirms with you before building anything, checks that you have a safe database to point at, fits the tool to your stack, generates the committed state, captures intent in comments through migrations with your consent, and wires generation to your migration process. +The assistant confirms with you first, checks that you have a safe database to point at, fits the tooling to your project, generates the readable state files, and offers to keep them up to date as your database changes. For a walkthrough of what to expect, see [docs/QUICKSTART.md](docs/QUICKSTART.md). -The skill instructs the agent to treat your data as sacred: to read the database read-only, never reset or wipe a database to obtain a clean state, never touch production without your explicit, informed consent, and bring decisions about schema, security, and indexing to you rather than taking them on its own. What any given agent actually does is outside this project's control; the skill makes these the rules it is told to follow. +## Your data stays safe -## The skill package +The skill instructs the assistant to treat your data as sacred: read-only access only, never resetting or wiping a database to get a clean state, never touching a production database without your clear and informed consent, and bringing any change to your schema, security, or indexing to you instead of deciding alone. -- `src/SKILL.md` is the canonical skill entry point. -- `src/references/` holds the method, the reference implementation guide, the reading and judgment guides, the commenting discipline, the layers guide, the other-databases guide, and the agent-instructions integration. -- `src/scripts/` is the runnable PostgreSQL reference implementation to read and adapt. -- `src/test-fixtures/` holds a generic example and verification prompts. +What an assistant ultimately does is outside this project's control. The skill's job is to make these the rules it is told to follow. -## Documentation +## What you get -- [docs/QUICKSTART.md](docs/QUICKSTART.md) - Install the skill and run it against a repository. -- [docs/INSTALL.md](docs/INSTALL.md) - Standalone and plugin installation. -- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - The skill's design, goal, and structure. -- [docs/RELEASING.md](docs/RELEASING.md) - Release checklist and packaging. -- [docs/VERSION.md](docs/VERSION.md) - Versioning and tag format. -- [docs/PROVENANCE.md](docs/PROVENANCE.md) - Attribution and distilled sources. -- [CONTRIBUTING.md](CONTRIBUTING.md), [SUPPORT.md](SUPPORT.md), [SECURITY.md](SECURITY.md). +Plain files under a `state/` folder in your repository: one navigable data file, one complete document of the whole schema, and one self-contained file per table, view, and function. You can open them, search them, paste one into a review, or hand them to another AI tool, all without opening the database. -## Background and project +## Learn more -- [docs/HOW-THIS-SKILL-WAS-BUILT.md](docs/HOW-THIS-SKILL-WAS-BUILT.md) - Its origin, the template that generated it, and how it was refined. -- [docs/FOUNDATIONS.md](docs/FOUNDATIONS.md) - The frameworks that shaped the skill, at a conceptual level. -- [docs/ROADMAP.md](docs/ROADMAP.md) - Where the skill is heading and why. -- [docs/ABOUT.md](docs/ABOUT.md) - The people and companies behind it. +- [docs/QUICKSTART.md](docs/QUICKSTART.md) and [docs/INSTALL.md](docs/INSTALL.md) to get started. +- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/FOUNDATIONS.md](docs/FOUNDATIONS.md) to understand the design and the ideas behind it. +- [docs/ROADMAP.md](docs/ROADMAP.md), [docs/HOW-THIS-SKILL-WAS-BUILT.md](docs/HOW-THIS-SKILL-WAS-BUILT.md), and [docs/ABOUT.md](docs/ABOUT.md) for where it is going and who builds it. +- [SUPPORT.md](SUPPORT.md) and [SECURITY.md](SECURITY.md) for help and reporting. ## For maintainers and contributors -These steps are for working on this repository, not for installing the skill. To install the skill, use the [Install](#install) section above. - -Clone the repository, then validate the package: +These steps are for working on this repository, not for installing the skill. Clone the repository, then validate the package: ```bash npm run validate @@ -92,12 +81,8 @@ Build the release assets for a tag: npm run package -- vX.Y.Z ``` -Use the intended release tag. Assets are written to `dist/assets/`. The contribution and release process is in [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/RELEASING.md](docs/RELEASING.md). - -## Author - -Authored and maintained by TechSpokes. See [docs/ABOUT.md](docs/ABOUT.md) for the people and companies behind the skill, and [docs/PROVENANCE.md](docs/PROVENANCE.md) for attribution. +Assets are written to `dist/assets/`. The contribution and release process is in [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/RELEASING.md](docs/RELEASING.md). -## License +## Credits and license -This repository is licensed under the terms in [LICENSE](LICENSE). +Authored and maintained by TechSpokes. See [docs/ABOUT.md](docs/ABOUT.md) for the people and companies behind the skill and [docs/PROVENANCE.md](docs/PROVENANCE.md) for attribution. This repository is licensed under the terms in [LICENSE](LICENSE). diff --git a/docs/releases/v1.4.0.md b/docs/releases/v1.4.0.md new file mode 100644 index 0000000..48aca70 --- /dev/null +++ b/docs/releases/v1.4.0.md @@ -0,0 +1,16 @@ +# Postgres Introspection Skill v1.4.0 + +This release makes the front page welcoming and rounds out the plugin metadata. + +## Highlights + +- The README now reads as a front page. It opens with what the skill gives you in plain language, then how to install and use it, and moves the conceptual and internal detail into the docs. +- Both plugin manifests now declare `"license": "MIT"`, and the Claude plugin manifest gains a top-level `"displayName"`, after a field-by-field check against the Claude Code and Codex plugin specifications. + +## Why it matters + +A newcomer landing on the repository now sees the value and the install path first, instead of internal structure. The plugin packages carry complete, spec-aligned metadata for the install surfaces that display it. + +## Notes + +Release tag: `v1.4.0`. diff --git a/package.json b/package.json index d002705..f6fd99c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "postgres-introspection", - "version": "1.3.0", + "version": "1.4.0", "private": true, "type": "module", "scripts": { diff --git a/packaging/claude-plugin/.claude-plugin/plugin.json b/packaging/claude-plugin/.claude-plugin/plugin.json index c3903d7..5dc79a2 100644 --- a/packaging/claude-plugin/.claude-plugin/plugin.json +++ b/packaging/claude-plugin/.claude-plugin/plugin.json @@ -1,12 +1,14 @@ { "name": "postgres-introspection", - "version": "1.3.0", + "displayName": "Database Introspection", + "version": "1.4.0", "description": "Teaches an AI agent to build a read-only database introspection capability inside the repository it is working in, rendering live database state into committed, navigable files. Database-agnostic method with a PostgreSQL reference implementation.", "author": { "name": "TechSpokes" }, "homepage": "https://github.com/TechSpokes/skill-postgres-introspection", "repository": "https://github.com/TechSpokes/skill-postgres-introspection", + "license": "MIT", "keywords": [ "agent-skill", "claude-plugin", diff --git a/packaging/codex-plugin/.codex-plugin/plugin.json b/packaging/codex-plugin/.codex-plugin/plugin.json index 982cb6f..2adb8cc 100644 --- a/packaging/codex-plugin/.codex-plugin/plugin.json +++ b/packaging/codex-plugin/.codex-plugin/plugin.json @@ -1,12 +1,13 @@ { "name": "postgres-introspection", - "version": "1.3.0", + "version": "1.4.0", "description": "Teaches an AI agent to build a read-only database introspection capability inside the repository it is working in, rendering live database state into committed, navigable files. Database-agnostic method with a PostgreSQL reference implementation.", "author": { "name": "TechSpokes" }, "homepage": "https://github.com/TechSpokes/skill-postgres-introspection", "repository": "https://github.com/TechSpokes/skill-postgres-introspection", + "license": "MIT", "keywords": [ "agent-skill", "codex-plugin",