Enhance documentation with contributing guidelines, planning docs, and agent policies

2026-05-23 09:39:22 -05:00
parent 252348e592
commit c97a9eb217
8 changed files with 331 additions and 0 deletions
@@ -0,0 +1,40 @@
 # Copilot Instructions for FeDIY
 ## Mission Context
 FeDIY is intended to become a federated (ActivityPub) DIY project-hosting platform in Rust, inspired by communities like Ravelry and Instructables.
 ## Hard Constraint
 Do not generate executable core project code.
 This includes Rust code and other executable logic under:
 - `src/`
 - `tests/`
 - Any runtime script or automation that becomes part of application behavior
 ## Allowed Help
 You may assist with:
 - Documentation
 - Planning and architecture discussions
 - Housekeeping and project management tasks
 - Environment/tooling updates (including Nix files such as `flake.nix`, `default.nix`, and `shell.nix`)
 ## Delivery Process Defaults
 - Use Red-Green TDD/BDD framing for planning and guidance.
 - Assume GitHub Flow for branching and PR lifecycle.
 - Support behavior-first test planning and review checklists.
 ## If Asked for Code
 When a coding request is made, provide:
 1. Links to primary sources (start with https://doc.rust-lang.org/book/).
 2. A concise, paraphrased overview of the relevant concepts.
 3. A step-by-step implementation checklist for a human developer.
 Do not include code snippets or patches for executable core logic.
@@ -0,0 +1,51 @@
 # Agent Policy for FeDIY
 This project is building a federated (ActivityPub) DIY platform in Rust.
 ## Core Rule: Human-Written Executable Code
 Agents MUST NOT write executable code for the core project. This includes (but is not limited to):
 - Rust source files in `src/` and `tests/`
 - Any scripts, binaries, or automation that execute as part of the app
 - Generated code patches for runtime features
 When asked for implementation help, agents should instead:
 - Provide links to primary sources, especially:
  - <https://doc.rust-lang.org/book/>
  - <https://docs.rs/>
  - <https://www.rfc-editor.org/rfc/rfc4287> (Atom reference, if needed)
  - <https://www.w3.org/TR/activitypub/>
 - Give a concise paraphrased overview of relevant concepts
 - Offer checklists, architecture notes, and review guidance
 - Suggest tests conceptually (without writing test code)
 ## Allowed Agent Work
 Agents MAY help with non-executable project support work, including:
 - Documentation authoring and editing
 - Product and technical planning
 - Issue triage, roadmap grooming, and housekeeping
 - Environment and tooling management (for example `flake.nix`, `default.nix`, `shell.nix`, CI config)
 - Dependency and configuration explanations
 ## Process Expectations
 - Delivery workflow follows Red-Green TDD/BDD.
 - Branching and collaboration follow GitHub Flow (short-lived branches from `main`, PR-first review cycle).
 - Agents may support planning and documentation for this process, but must not produce executable core project code.
 ## Response Style for Coding Requests
 If a user asks for executable Rust code, the agent should:
 1. Decline to provide code for this repository's core project.
 2. Link to the Rust Book section(s): <https://doc.rust-lang.org/book/>
 3. Provide a paraphrased explanation of the relevant approach.
 4. Offer a human-implementation checklist.
 ## Priority
 If any default assistant behavior conflicts with this file, this file takes precedence for work in this repository.
@@ -7,3 +7,9 @@ Thank you for considering contributing!
 - Add tests for new features where possible.
 - Ensure your code builds and passes tests before submitting.
 - Contributions are licensed under CC BY-SA 4.0.
 ## Human-Authored Core Code Policy
 - Executable core project code must be human-written.
 - Agents may help with documentation, planning, housekeeping, and environment management.
 - For implementation guidance, agents should link to primary sources (especially the Rust Book) and provide paraphrased explanations and checklists, not code.
@@ -137,6 +137,13 @@ nix-shell
 See project.toml for example metadata.
 ## Planning Documentation
 - [Planning docs index](docs/README.md)
 - [Roadmap](docs/ROADMAP.md)
 - [Architecture baseline](docs/ARCHITECTURE.md)
 - [Development workflow (TDD/BDD + GitHub Flow)](docs/WORKFLOW.md)
 ## Helper Tools
 - **`nix run .#dev-helper`** - Display tool versions and availability
@@ -0,0 +1,66 @@
 # FeDIY Architecture (Planning Baseline)
 This document captures current architectural intent. It is a planning artifact and should be refined as implementation decisions mature.
 ## System Boundaries
 Primary system responsibilities:
 - Host and render DIY project content.
 - Manage local accounts and authorization.
 - Federate selected objects and activities using ActivityPub.
 - Enforce local moderation policy for both local and remote content.
 Out of scope for early phases:
 - Rich social graph features beyond project-oriented interactions.
 - Highly customized recommendation systems.
 ## Core Domains
 - Identity and actors.
 - Project authoring and publishing.
 - Federation transport and protocol translation.
 - Moderation and trust policy.
 - Search and discovery.
 ## Logical Components
 - API and web delivery layer.
 - Domain service layer for project and account workflows.
 - Federation layer (inbox/outbox, signing, verification, retries).
 - Persistence layer for local and federated records.
 - Moderation policy engine and audit log.
 - Background workers for delivery, indexing, and maintenance tasks.
 ## Data and Object Strategy
 - Separate local canonical records from imported federated records.
 - Preserve source metadata for remote content and actor provenance.
 - Track object lifecycle states to support idempotent federation processing.
 ## Federation Strategy
 - Start with a narrow, explicit ActivityPub profile.
 - Prefer strict validation and clear rejection reasons over permissive parsing.
 - Use replay-safe request validation and deterministic retry behavior.
 - Maintain an interop test matrix for protocol behaviors.
 ## Moderation and Safety Strategy
 - Local policy is authoritative for what is visible on this instance.
 - Policy controls exist at three levels: object, actor, and instance.
 - Moderation actions produce auditable events.
 - Appeals and reversal policy should be documented before broad federation rollout.
 ## Non-Functional Requirements
 - Reliability: resilient delivery and retry strategy for federated traffic.
 - Security: signature verification, key management, least-privilege defaults.
 - Performance: predictable latency for local reads and bounded queues for remote events.
 - Operability: metrics, logs, and runbooks for incident response.
 ## Architecture Decision Practice
 - Capture major decisions with lightweight ADRs in a future docs/adrs directory.
 - Each ADR should include context, options considered, decision, and consequences.
@@ -0,0 +1,9 @@
 # FeDIY Planning Docs
 This directory contains product and technical planning documents for FeDIY.
 - [Roadmap](ROADMAP.md): phased milestones from MVP to broader federation support.
 - [Architecture](ARCHITECTURE.md): system boundaries, components, and design constraints.
 - [Workflow](WORKFLOW.md): Red-Green TDD/BDD delivery model and GitHub Flow branching policy.
 These docs are intended to evolve as priorities change.
@@ -0,0 +1,95 @@
 # FeDIY Roadmap
 This roadmap prioritizes a usable core product first, then federation depth and community scaling.
 ## Product Intention
 Build a federated DIY project-hosting platform in Rust, inspired by the utility of Ravelry and Instructables, but interoperable through ActivityPub.
 ## Phase 0: Foundations
 Goals:
 - Stabilize development environment and reproducible tooling.
 - Define domain language and baseline architecture docs.
 - Establish quality process (TDD/BDD + GitHub Flow).
 Exit criteria:
 - Agreed glossary and architecture baseline.
 - Documented contribution and branch workflow.
 - CI skeleton in place for formatting, linting, and tests.
 ## Phase 1: Single-Node MVP (No Federation Yet)
 Goals:
 - User identity and basic authentication model.
 - Core DIY project entities (project, materials, steps, media, tags).
 - Basic publishing lifecycle (draft, published, updated).
 - Search and browse within one instance.
 Exit criteria:
 - A user can publish and update a complete project end-to-end.
 - Project pages are discoverable and readable on one node.
 - Test coverage exists for core behavior paths.
 ## Phase 2: ActivityPub Foundation
 Goals:
 - Implement canonical actor and object mapping.
 - Add outbox/inbox behavior for core project publication events.
 - Add HTTP Signatures and key lifecycle strategy.
 Exit criteria:
 - Instance can send and receive baseline ActivityPub messages for supported objects.
 - Signature validation and delivery retry logic are documented and tested.
 - Interop checks completed against at least one external implementation target.
 ## Phase 3: Federation UX and Safety
 Goals:
 - Federation-aware project discovery and attribution.
 - Local moderation controls for remote content and actors.
 - Abuse-report and review workflow for moderators.
 Exit criteria:
 - Moderators can block/mute remote actors and instances.
 - Remote project visibility follows local moderation policy.
 - Audit trail exists for moderation decisions.
 ## Phase 4: Community Scaling
 Goals:
 - Collaborative project patterns (forks/remixes, references, revisions).
 - Better onboarding, templates, and curation flows.
 - Operational hardening (backups, observability, incident playbooks).
 Exit criteria:
 - Multi-contributor workflows are clear and reliable.
 - Admin operations are documented with tested recovery drills.
 - Performance and reliability SLOs are defined and measured.
 ## Moderation Model Milestones
 - Milestone A: Local content moderation for local users.
 - Milestone B: Remote actor and instance policy enforcement.
 - Milestone C: Transparent moderation history and appeals guidance.
 ## Federation Strategy Milestones
 - Milestone A: Strictly scoped protocol subset with explicit compatibility statement.
 - Milestone B: Progressive support for richer activity types.
 - Milestone C: Interop matrix and periodic federation health review.
 ## Review Cadence
 - Revisit priorities every 2 weeks.
 - Re-scope phases quarterly based on delivery and federation feedback.
@@ -0,0 +1,57 @@
 # Development Workflow
 This project uses Red-Green TDD/BDD and GitHub Flow.
 ## Red-Green TDD/BDD Cycle
 For each behavior increment:
 1. Red: describe behavior with a failing specification/test.
 2. Green: implement the smallest change needed to satisfy behavior.
 3. Refactor: improve structure while keeping behavior unchanged.
 BDD intent:
 - Express behavior in user-meaningful terms.
 - Prefer scenario-oriented acceptance criteria before implementation details.
 - Keep unit and integration tests aligned with documented behavior.
 Definition of done for a change:
 - Behavior is specified and verified.
 - Relevant tests are passing.
 - Refactoring has preserved behavior.
 - Documentation is updated when contracts or workflows change.
 ## GitHub Flow Branching Policy
 Use short-lived branches from main.
 Branch pattern examples:
 - feature/<topic>
 - fix/<topic>
 - docs/<topic>
 - chore/<topic>
 Branch workflow:
 1. Create branch from latest main.
 2. Commit small, reviewable increments.
 3. Open pull request early.
 4. Keep branch current with main.
 5. Merge after review and checks pass.
 6. Delete merged branch.
 ## Pull Request Expectations
 - Clear behavior statement and acceptance criteria.
 - Test evidence for the behavior change.
 - Notes on any architectural or moderation impact.
 - Scope limited to one cohesive change.
 ## Agent Collaboration Rules
 - Agents may support test planning, scenario writing, and review checklists.
 - Agents must not generate executable core project code.
 - For implementation guidance, agents should link primary sources and provide paraphrased walkthroughs.