Skip to content

[#10875] improvement(agent-skills): Add gravitino-design-doc skill to enforce design document structure#10876

Merged
jerryshao merged 3 commits intoapache:mainfrom
jerryshao:10875-gravitino-design-doc-skill
May 7, 2026
Merged

[#10875] improvement(agent-skills): Add gravitino-design-doc skill to enforce design document structure#10876
jerryshao merged 3 commits intoapache:mainfrom
jerryshao:10875-gravitino-design-doc-skill

Conversation

@jerryshao
Copy link
Copy Markdown
Contributor

What changes were proposed in this pull request?

Adds a new gravitino-design-doc Claude Code skill under agent-skills/ that enforces consistent structure and content quality for Apache Gravitino design documents.

The skill requires the following sections in order:

  1. Apache License Header
  2. Title
  3. Background — current state and problem, not the solution
  4. Goals — concrete and verifiable
  5. Non-Goals — explicit scope carve-outs with rationale
  6. Solution Investigations — alternatives with pros/cons and rejection reasons
  7. Proposal — API design, data model, implementation approach
  8. Task Breakdown — one actionable task per GitHub issue/PR, ordered by dependency

Why are the changes needed?

Closes #10875. With spec-driven development, design doc PRs are now required before major features. Without an enforced structure, doc quality is inconsistent and reviewers repeatedly request the same fixes.

How was this patch tested?

N/A — documentation/tooling only change.

🤖 Generated with Claude Code

…ill to enforce design document structure

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@github-actions
Copy link
Copy Markdown

github-actions Bot commented Apr 27, 2026

Code Coverage Report

Overall Project 65.58% 🟢
Files changed No Java source files changed -

Module Coverage
aliyun 1.73% 🔴
api 47.13% 🟢
authorization-common 85.96% 🟢
aws 1.1% 🔴
azure 2.6% 🔴
catalog-common 10.2% 🔴
catalog-fileset 80.02% 🟢
catalog-glue 82.47% 🟢
catalog-hive 81.83% 🟢
catalog-jdbc-clickhouse 79.18% 🟢
catalog-jdbc-common 43.93% 🟢
catalog-jdbc-doris 80.28% 🟢
catalog-jdbc-hologres 54.03% 🟢
catalog-jdbc-mysql 79.23% 🟢
catalog-jdbc-oceanbase 78.38% 🟢
catalog-jdbc-postgresql 82.05% 🟢
catalog-jdbc-starrocks 78.27% 🟢
catalog-kafka 77.01% 🟢
catalog-lakehouse-generic 45.07% 🟢
catalog-lakehouse-hudi 79.1% 🟢
catalog-lakehouse-iceberg 86.98% 🟢
catalog-lakehouse-paimon 77.71% 🟢
catalog-model 77.72% 🟢
cli 44.51% 🟢
client-java 77.63% 🟢
common 48.75% 🟢
core 81.6% 🟢
filesystem-hadoop3 76.97% 🟢
flink 40.55% 🟢
flink-runtime 0.0% 🔴
gcp 14.2% 🔴
hadoop-common 10.39% 🔴
hive-metastore-common 46.83% 🟢
iceberg-common 55.24% 🟢
iceberg-rest-server 68.05% 🟢
integration-test-common 0.0% 🔴
jobs 66.17% 🟢
lance-common 23.88% 🔴
lance-rest-server 57.84% 🟢
lineage 53.02% 🟢
optimizer 82.87% 🟢
optimizer-api 21.95% 🔴
server 85.46% 🟢
server-common 70.01% 🟢
spark 32.79% 🔴
spark-common 39.09% 🔴
trino-connector 35.14% 🔴

…kill agent-agnostic

Remove Claude Code-specific references from README so the skill works
with any AI agent.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@jerryshao
Copy link
Copy Markdown
Contributor Author

@roryqi @mchades can you please help to review this?

Do you suggest moving this skill to the .claude folder to enable it by default?

@roryqi
Copy link
Copy Markdown
Contributor

roryqi commented Apr 30, 2026

@roryqi @mchades can you please help to review this?

Do you suggest moving this skill to the .claude folder to enable it by default?

Prefer enabling by default.

Comment thread .claude/skills/gravitino-design-doc/SKILL.md
Comment thread .claude/skills/gravitino-design-doc/SKILL.md
…kill to .claude/skills for default enablement

- Move gravitino-design-doc skill from agent-skills/ to .claude/skills/ so it is auto-discovered by Claude Code for all contributors
- Remove .claude from .gitignore and add .claude/settings.local.json instead so project skills are tracked while local settings remain private
- Expand Proposal section with API changes format (new vs changed REST APIs), user process, and implementation process sub-sections
- Update Quality Checklist and Common Mistakes table to reflect the new required sub-sections

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@jerryshao jerryshao self-assigned this May 6, 2026
@jerryshao jerryshao requested review from mchades and roryqi May 6, 2026 10:11
@jerryshao jerryshao merged commit ef303f2 into apache:main May 7, 2026
26 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Improvement] Enforce consistent design document structure with a Claude Code skill

3 participants