From d47feaf2ff8ef79e3860e6f310848a8c938a888c Mon Sep 17 00:00:00 2001 From: Vaishnav88sk Date: Wed, 2 Sep 2026 22:21:23 +0530 Subject: [PATCH] docs: adopt AGENTS.md for AI coding assistants Signed-off-by: Vaishnav88sk --- .github/copilot-instructions.md | 1 + AGENTS.md | 27 +++++++++++++++++++++++++++ ARCHITECTURE.md | 17 +++++++++++++++++ CLAUDE.md | 1 + DESIGN.md | 16 ++++++++++++++++ PRODUCT.md | 13 +++++++++++++ 6 files changed, 75 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 AGENTS.md create mode 100644 ARCHITECTURE.md create mode 100644 CLAUDE.md create mode 100644 DESIGN.md create mode 100644 PRODUCT.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5f8a27a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,27 @@ +# AGENTS + +Before making changes, review: +- @PRODUCT.md - Product vision, features, and roadmap +- @ARCHITECTURE.md - System design, interfaces, and directory structure +- @DESIGN.md - Design principles, patterns, and best practices +- @CONTRIBUTING.md - Coding standards, testing, and PR process + +## 1. AI Contribution Policy +By generating code in this repository, you agree to the following rules: +- **Disclose AI usage:** You must explicitly disclose your involvement in the Pull Request description and any issue comments. +- **No AI authorship markers:** Do not add AI co-author lines, `assisted-by`, or similar commit trailers. +- **Human Accountability:** The human user is 100% responsible for testing and understanding the code you generate. +- **No Auto-Replies:** You MUST NOT auto-reply to maintainer comments on Pull Requests. + +## 2. Code Formatting (Mandatory) +Microcks CLI enforces standard Go formatting. +**Before any commit**, you must run: +```bash +go fmt ./... +``` + +## 3. Building and Testing +Microcks CLI is a Go-based command-line tool. +- To build the CLI locally: `make build-local` +- To run tests: `go test ./...` +- For detailed instructions, read @CONTRIBUTING.md. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..82cb658 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,17 @@ +# Architecture + +Microcks CLI is a Go-based command-line tool designed for interacting with Microcks server APIs, launching tests, and importing artifacts. + +## Core Components +- **CLI Commands:** Built using a modern Go CLI framework (e.g., Cobra), providing subcommands like `start`, `stop`, `import`, `test`, etc. +- **Microcks API Client:** Communicates with the Microcks backend REST APIs to perform operations. +- **Keycloak Integration:** Handles authentication and token management for secure interactions with the backend. +- **Local Ephemeral Runner:** Employs Testcontainers to spin up ephemeral Microcks instances for local dry-run contract testing (`microcks test --dry-run`). + +## Structure +- `cmd/`: Contains the entry points and CLI command definitions. +- `pkg/`: Core packages and business logic. +- `documentation/`: Additional documentation. + +## Deployment +Available as a standalone binary for Linux, macOS, and Windows, and as a container image (`quay.io/microcks/microcks-cli`) for CI/CD integration. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 0000000..a208b4e --- /dev/null +++ b/DESIGN.md @@ -0,0 +1,16 @@ +# Design + +This document outlines the core design principles and patterns used in the Microcks CLI codebase. + +## Design Principles +- **Simplicity:** The CLI should be easy to use with minimal dependencies, providing a straightforward developer experience. +- **CI/CD Readiness:** Designed to be easily integrated into pipelines (GitHub Actions, Jenkins, Tekton) with machine-readable outputs (JSON, YAML, GitHub Actions). +- **Graceful Error Handling:** Code under `pkg/` and `cmd/` must return errors using the internal `errors` package (e.g., `errors.Wrap(errors.KindConnection, err)`), never exiting or panicking arbitrarily. + +## Coding Standards +- **Go Standard:** Strict adherence to idiomatic Go formatting (`go fmt`). +- **Error Types:** Follow the guidelines in `documentation/error-handling.md` and use the specific exit codes (0-2 for standard, 11-20 for Microcks-specific). + +## Best Practices +- **Modularity:** Keep command handlers thin and delegate business logic to packages in `pkg/`. +- **Testability:** Provide dry-run options and use ephemeral test environments (Testcontainers) when necessary. diff --git a/PRODUCT.md b/PRODUCT.md new file mode 100644 index 0000000..f0b6b0b --- /dev/null +++ b/PRODUCT.md @@ -0,0 +1,13 @@ +# Product + +## Vision +Microcks CLI provides a simple and powerful command-line interface for the Microcks API Mocking and Testing platform. It empowers developers and CI/CD pipelines to interact with Microcks, deploy tests, and import artifacts with minimal overhead. + +## Key Features +- **Pipeline Integration:** Native support for GitHub Actions, Tekton, and other CI/CD tools to trigger contract tests and API imports. +- **Local Contract Testing:** Support for zero-infrastructure local testing via `microcks test --dry-run` and Testcontainers. +- **Artifact Management:** Easily import API specifications (OpenAPI, AsyncAPI, Postman, etc.) from local directories or remote URLs. +- **Machine-Readable Outputs:** Configurable output formats (JSON, YAML, GitHub Actions) for seamless integration with automation tools. + +## Roadmap +Enhance the Developer Experience by providing deeper integrations with IDEs, supporting more complex testing scenarios, and continuously aligning with the features of the Microcks core platform.