Welcome to the Bluefly.io code repository. By logging in, you agree to comply with our terms of service and code of conduct.

Skip to content

Remove All Documentation Markdown Files - Migrate to GitLab Wiki

Objective

Remove all markdown documentation files from OSSA repository. This is a specification repository containing only YAML and JSON - documentation belongs in GitLab Wiki.

Problem Statement

OSSA repo currently has markdown files that don't belong:

  • specifications/core/*.md
  • specifications/compliance/requirements.md
  • specifications/protocols/agent-communication-protocol.md
  • specifications/README.md
  • SETUP.md
  • Various other documentation files

OSSA is a specification repo like OpenAPI Specification - it should contain:

  • ✅ JSON schemas (.json)
  • ✅ Example manifests (.yml, .yaml)
  • ✅ OpenAPI specifications (.openapi.yml)
  • ❌ Documentation markdown files (goes to GitLab Wiki)

Files to Remove

# Remove all non-essential markdown files
rm -rf specifications/core/*.md
rm -rf specifications/compliance/requirements.md
rm -rf specifications/protocols/*.md
rm -rf specifications/README.md
rm SETUP.md

# Keep only:
# - CHANGELOG.md (standard for releases)
# - README.md (repo landing page - keep minimal)
# - LICENSE (required)

README.md - Keep Minimal

The README should be extremely minimal, just pointing to resources:

# OSSA - Open Standard for Scalable Agents

The OpenAPI for AI Agents.

## Quick Start

- **Specification**: [spec/ossa-1.0.schema.json](spec/ossa-1.0.schema.json)
- **Examples**: [spec/examples/](spec/examples/)
- **Documentation**: [GitLab Wiki](https://gitlab.bluefly.io/llm/openapi-ai-agents-standard/-/wikis/home)
- **Issues**: [Issue Tracker](https://gitlab.bluefly.io/llm/openapi-ai-agents-standard/-/issues)

## Installation

```bash
npm install @ossa/specification

Validate a Manifest

npx ajv validate -s spec/ossa-1.0.schema.json -d your-agent.yml

License

Apache 2.0


## GitLab Wiki Structure

All documentation should move to GitLab Wiki:

📁 GitLab Wiki ├── Home.md ├── Getting-Started.md ├── Schema-Reference.md ├── Examples/ │ ├── Docker-Runtime.md │ ├── Kubernetes-Runtime.md │ ├── Serverless-Runtime.md ├── Integration/ │ ├── HTTP-Protocol.md │ ├── gRPC-Protocol.md │ ├── MCP-Protocol.md ├── Observability/ │ ├── Activity-Streaming.md │ ├── Conversation-Tracking.md │ ├── Phoenix-Arize.md ├── Compliance/ │ ├── FedRAMP.md │ ├── HIPAA.md │ ├── GDPR.md ├── Tooling/ │ ├── CLI-Tools.md │ ├── VS-Code-Extension.md │ ├── GitHub-Actions.md │ ├── Kubernetes-Operator.md ├── Enterprise/ │ ├── Early-Adopter-Program.md │ ├── Training-Certification.md │ ├── Support-Tiers.md ├── API-Reference/ │ ├── Registry-API.md │ ├── Validation-API.md └── Contributing.md


## Migration Checklist

- [ ] Identify all markdown files in repo (excluding node_modules)
- [ ] Create corresponding GitLab Wiki pages
- [ ] Migrate content from markdown files to Wiki
- [ ] Update any internal references
- [ ] Delete markdown files from repo
- [ ] Update README.md to minimal version
- [ ] Update CI/CD to skip documentation building from repo
- [ ] Verify no broken links

## Repository Structure (After Cleanup)

ossa/ ├── spec/ │ ├── ossa-1.0.schema.json # Main specification │ └── examples/ # Example OSSA manifests │ ├── compliance-agent.yml │ ├── chat-agent.yml │ ├── orchestrator-agent.yml │ └── semantic-chat-agent.yml ├── openapi/ # OpenAPI specs (if needed) │ └── ossa-registry.openapi.yml ├── tests/ # Validation tests │ └── validation-suite/ │ ├── schema-validator.test.ts │ └── edge-cases.test.ts ├── .gitlab-ci.yml # CI/CD pipeline ├── package.json # NPM package definition ├── tsconfig.json # TypeScript config ├── jest.config.js # Test config ├── CHANGELOG.md # Release notes (KEEP) ├── README.md # Minimal landing page (KEEP MINIMAL) └── LICENSE # Apache 2.0 (KEEP)


## Acceptance Criteria

- [ ] All .md files removed except CHANGELOG.md, README.md, LICENSE
- [ ] README.md reduced to <50 lines (just links to Wiki)
- [ ] GitLab Wiki structure created
- [ ] All documentation migrated to Wiki
- [ ] CI/CD no longer generates documentation from repo
- [ ] Repository is specification-only (JSON/YAML)
- [ ] All project references updated to point to Wiki

## References

This aligns with how other specification repositories work:
- **OpenAPI Specification**: Only YAML specs, docs in separate repo
- **JSON Schema**: Only JSON schemas, docs on separate site
- **Kubernetes API**: Only Go types, docs on k8s.io

## Files to Modify

- `README.md` - Reduce to minimal version
- `.gitlab-ci.yml` - Remove doc building steps
- Delete: All `specifications/**/*.md` files