jeffrey228/vk_hackathon
1
0
Fork 0
forked from zovos/vk_hackathon
Code Pull requests Activity
vk_hackathon/.agents/skills/team-sync-hackathon/SKILL.md

7 KiB
Raw Blame History

name description
team-sync-hackathon Use this skill for any work inside this repository when the task involves collaborative development, continuing previous work, restoring project context, updating shared progress logs, handing off work to another Codex or human, or bootstrapping the local dev stack. Do not use for unrelated one-off questions outside the repo.

Team Sync Hackathon Skill

This skill makes Codex behave like a persistent teammate inside the repository.

Its purpose is to:

  • restore context at the start of every session
  • keep a shared machine-readable and human-readable progress trail
  • reduce repeated analysis
  • make handoff between humans and Codex reliable
  • automatically orient to the current repo state before coding
  • keep the project runnable locally whenever validation is needed

Core rule

Do not start changing code blindly.

First restore context, then inspect git state, then inspect runtime state, then work, then write handoff.

If context is missing, create it.

Shared state directory

Use .ai_update/ as the canonical shared state area.

Required files:

  • .ai_update/current_status.md
  • .ai_update/handoff.md
  • .ai_update/changelog.md
  • .ai_update/touched_files.md
  • .ai_update/sessions/ (directory with per-session notes)

These files are part of the collaboration workflow and should be committed unless the team explicitly decides otherwise.

Mandatory startup workflow

At the beginning of each repo task, do this in order:

  1. Read:

    • AGENTS.md
    • README.md
    • relevant docs/config files
    • .ai_update/current_status.md
    • .ai_update/handoff.md
    • latest 3 to 5 files from .ai_update/sessions/
    • .ai_update/changelog.md
    • .ai_update/touched_files.md

  2. Inspect repository state:

    • git status --short --branch
    • git log --oneline --decorate -n 15
    • inspect main app entrypoints and service layout
    • identify current branch
    • identify uncommitted work
    • identify likely active area of development

  3. If .ai_update/ files are missing:

    • create them immediately
    • infer current project state from repository files and git history
    • write a minimal baseline before making new code changes

  4. Create a new session note:

    • .ai_update/sessions/YYYY-MM-DD_HH-MM-SS.md
    • include:
      • task requested
      • starting branch
      • starting commit
      • initial repo observations
      • assumptions
      • risks/blockers

  5. Only after that begin implementation.

Runtime bootstrapping workflow

When local validation is required, use the least destructive startup path.

Try in this order:

  1. If ./bin/codex-start exists, use it.
  2. Else if docker-compose.yml exists:
    • check whether services are already up
    • if not, run docker compose up -d --build
  3. Else if compose.yaml or compose.yml exists:
    • run docker compose up -d --build
  4. Else if Makefile exists and has a relevant target:
    • try make dev
    • otherwise make up
    • otherwise make run
  5. Else inspect project docs for the correct startup command.

Rules:

  • do not run destructive cleanup automatically
  • do not remove volumes automatically
  • do not rebuild everything if a simple start is enough
  • if startup fails, record the failure and exact reason in .ai_update/current_status.md and the current session note

Required logging during work

For each meaningful step, keep .ai_update/ current.

Update .ai_update/current_status.md

This file is the canonical current snapshot.

It must always contain:

  • current goal
  • done
  • in progress
  • blocked
  • next actions
  • current branch
  • validation status
  • known risks

Append to .ai_update/changelog.md

Append a short entry for every meaningful change:

  • timestamp
  • what changed
  • why
  • files
  • verification result

Update .ai_update/touched_files.md

Maintain a concise list:

  • file path
  • purpose
  • why touched
  • whether complete/incomplete
  • whether needs review

Write session notes

Each session file should capture:

  • objective
  • context read
  • commands run
  • findings
  • code changes
  • test results
  • unresolved issues
  • handoff notes

Mandatory handoff before stopping

Before ending the session:

  1. Update .ai_update/current_status.md
  2. Update .ai_update/handoff.md
  3. Append .ai_update/changelog.md
  4. Update .ai_update/touched_files.md
  5. Finalize current session note

handoff.md must answer:

  • what was completed
  • what was not completed
  • what the next Codex/human should do first
  • what files matter most
  • how to run/verify
  • what is risky or fragile
  • whether there are uncommitted changes

Another engineer should be able to continue without rereading the full repo history.

Repository-specific guidance for this hackathon

Assume this repository follows a hackathon task with:

  • an indexing service
  • a search service
  • vector storage in Qdrant
  • fixed API contracts for /index, /sparse_embedding, and /search
  • local docker-based development
  • quality measured by retrieval relevance rather than just code style

When working on search/index logic:

  • preserve public request/response contracts
  • do not introduce runtime internet dependency inside index/search containers
  • prefer retrieval quality improvements over cosmetic refactors
  • avoid breaking dockerized local startup
  • keep local validation straightforward

For search logic, prefer this query priority:

  1. question.search_text
  2. fallback to question.text
  3. enrich with question.variants
  4. consider question.hyde
  5. consider question.keywords
  6. consider question.entities
  7. consider question.date_mentions and question.date_range
  8. keep rerank/retrieval consistent with top-50 relevance goals

For indexing logic:

  • keep chunking explainable
  • preserve message_ids coverage clarity
  • think explicitly about page_content, dense_content, and sparse_content
  • log chunking and retrieval decisions if they affect quality significantly

Collaboration rules

  • Never assume previous work is obsolete without evidence.
  • Read before rewriting.
  • Prefer extending existing modules over creating parallel implementations.
  • Preserve teammate intent when possible.
  • If you must replace an approach, document why in .ai_update/changelog.md and handoff.md.

Git rules

  • Do not commit unrelated changes.
  • Do not revert teammate changes without explicit reason.
  • Do not force push unless explicitly instructed.
  • Before commit, summarize exactly what changed in .ai_update/.
  • Commit messages should be specific and scoped.

Preferred commit style:

  • search: use search_text with fallback to text
  • index: enrich sparse content with metadata
  • infra: add codex shared handoff workflow

Minimal file templates

If files are missing, initialize them with these templates.

.ai_update/current_status.md

# Current Status

## Current goal
-

## Done
- 

## In progress
- 

## Blocked
- 

## Next actions
- 

## Current branch
-

## Validation
- Not run / Passed / Failed

## Risks / notes
-